{"id":13901370,"url":"https://github.com/rhysd/electron-in-page-search","last_synced_at":"2025-08-21T02:31:53.192Z","repository":{"id":12994393,"uuid":"73331756","full_name":"rhysd/electron-in-page-search","owner":"rhysd","description":"Module to introduce Electron's native in-page search avoiding pitfalls","archived":false,"fork":false,"pushed_at":"2022-12-30T17:52:12.000Z","size":427,"stargazers_count":72,"open_issues_count":10,"forks_count":10,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-12-10T03:32:05.634Z","etag":null,"topics":["electron","page","search"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/rhysd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-10T00:06:40.000Z","updated_at":"2024-07-19T05:02:23.000Z","dependencies_parsed_at":"2023-01-13T17:14:58.729Z","dependency_job_id":null,"html_url":"https://github.com/rhysd/electron-in-page-search","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Felectron-in-page-search","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Felectron-in-page-search/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Felectron-in-page-search/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/rhysd%2Felectron-in-page-search/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/rhysd","download_url":"https://codeload.github.com/rhysd/electron-in-page-search/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":230479864,"owners_count":18232630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["electron","page","search"],"created_at":"2024-08-06T21:01:17.550Z","updated_at":"2024-12-19T18:17:59.769Z","avatar_url":"https://github.com/rhysd.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"In-Page Search for Electron Applications\n========================================\n[![npm version](https://badge.fury.io/js/electron-in-page-search.svg)](https://www.npmjs.com/package/electron-in-page-search)\n[![Build Status on Travis CI](https://travis-ci.org/rhysd/electron-in-page-search.svg?branch=master)](https://travis-ci.org/rhysd/electron-in-page-search)\n[![Build Status on AppVeyor](https://ci.appveyor.com/api/projects/status/k80y8ccgpbt1ba57?svg=true)](https://ci.appveyor.com/project/rhysd/electron-in-page-search)\n\nThis package provides Chrome's native in-page search feature to Electron applications.\nElectron exposes Chrome's native API to JavaScript. But native in-page search API has\nsome pitfalls and stateful. So this package wraps it and provide provide more easy,\npitfall-free APIs.\n\n![screenshot](https://github.com/rhysd/ss/blob/master/electron-in-page-search/main.gif?raw=true)\n\nIn-page search can be used for browser window or webview (`BrowserWindow` instance or\n`\u003cwebview\u003e` tag) in Electron app. You can use only one function for both of them\nin renderer process.\n\n```javascript\n// Pass current browser window's WebContents instance\nconst searchInWindow = searchInPage(remote.getCurrentWebContents());\n\n// Pass \u003cwebview\u003e instance\nconst searchInWebview = searchInPage(document.getElementById('my-webview'));\n\n// Open inner window made with \u003cwebview\u003e for in-page search\n\n// Search some text in the browser window\nsearchInWindow.openSearchWindow();\n\n// Search some text in the webview\nsearchInWebview.openSearchWindow();\n```\n\nThis package works cross platform (macOS, Linux and Windows) with running CI on them\n(Travis CI for macOS and Linux, AppVeyor for Windows).\n\n\n\n## Installation\n\n```\n$ npm install --save electron-in-page-search\n```\n\n\n\n## Examples\n\nTwo examples are added. So please see the code of working app there.\n\n- [Search in browser window](example/browser-window)\n- [Search in `\u003cwebview\u003e`](example/webview)\n\nYou can try them by cloning this repository.\n\n```\n$ git clone https://github.com/rhysd/electron-in-page-search.git\n$ cd electron-in-page-search\n$ npm install\n$ npm run build\n$ npm run example # Run browser window example\n$ cd example/webview/\n$ npm start # Run webview example\n```\n\nYou can also see [the real world example](https://github.com/rhysd/Chromenu).\n\nTo know APIs for this package, you can see [TypeScript's type definitions](index.d.ts).\n\n\n\n## Usage\n\nWhen you want to use in-page search in app, call `searchInPage` function to create an `InPageSearch` instance.\n\n```javascript\nimport searchInPage from 'electron-in-page-search';\n// or\nconst searchInPage = require('electron-in-page-search').default;\n\nimport {remote} from 'electron';\n\nconst inPageSearch = searchInPage(remote.getCurrentWebContents());\n\ndocument.getElementById('some-button').addEventListener('click', () =\u003e {\n    inPageSearch.openSearchWindow();\n});\n```\n\nWhen calling `searchInPage`, it creates a `\u003cwebview\u003e` element for search window.\nThis `\u003cwebview\u003e` can avoid that in-page search finds the text in the search window.\n\nThe webview has a class property `electron-in-page-search-window search-inactive` by default.\nThen `openSearchWindow` is called, the webview has a class property `electron-in-page-search-window search-active`\nwhile searching. So you can styling the search window webview by CSS like below:\n\n```css\n.electron-in-page-search-window {\n  width: 300px;\n  height: 36px;\n  background-color: white;\n}\n\n.electron-in-page-search-window.search-inactive {\n  visibility: hidden;\n}\n\n.electron-in-page-search-window.search-active {\n  visibility: visible;\n}\n```\n\nYou can control background color of search window by adding `background-color`\n(in above, `white` is specified). You can customize CSS further (please see below\n'Customization' section).\n\nPlease see [example's style](example/browser-window/style.css) for live example.\n\nThe search window contains 'back' button, 'forward' button, 'close' button and query form.\nApplication users can input a query and click them (or press enter key in the form) to start\nthe in-page search.\nRepeating to press enter key or clicking 'back'/'forward' buttons moves a focus on hit words.\nFinally the users can close a search window by clicking 'close' button to stop the search.\n\nAfter a search window closing, the window's class property will be `electron-in-page-search-window search-inactive`\nagain.\n\nThe search window `\u003cwebview\u003e` is mounted to `document.body` (or an element specified with `searchWindowParent` option).\nWhen you want to destroy `InPageSearch` instance, please ensure to call `.finalize()` method.\nIt will unmount the search window `\u003cwebview\u003e` from DOM.\n\n\n\n## Development\n\n### Debugging\n\nIf you want to see a DevTools of search window, please pass `openDevToolsOfSearchWindow`\nproperty to `searchInPage` function as below.\n\n```javascript\nsearchInPage(webContents, { openDevToolsOfSearchWindow: true });\n```\n\nIt opens the DevTools with detach mode.\n\nAnd this package also supports logging. When `$ELECTRON_IN_PAGE_SEARCH_DEBUG` environment\nvariable is not empty, it outputs logs with `console.log` in rendrer process.\n\n### TypeScript\n\nThis package is written in [TypeScript](https://github.com/Microsoft/TypeScript) and ready for TypeScript.\nYou need not to prepare type definition file for this package because [index.d.ts](index.d.ts) is\nalready in this package.\n\n```typescript\nimport searchInPage, {InPageSearch} from 'electron-in-page-search';\n\nlet search: InPageSearch;\nconst elem = document.createElement('webview');\nelem.src = 'https://example.com';\n\ndocument.getElementById('main').appendChild(elem);\nelem.on('dom-ready', () =\u003e {\n    search = searchInPage(elem);\n});\n\ndocument.getElementById('search-button').addEventListener('click', () =\u003e {\n    if (search) {\n        search.openSearchWindow();\n    }\n});\n```\n\n### My Environment\n\nI'm testing this package with below OS\n\n- macOS 10.12, OS X 10.11.6\n- Ubuntu Linux 16.04 LTS\n- Windows 8.1\n\n\n\n## Customization\n\n### Use my own CSS for search window\n\nIf you want to use a default search window but don't want to use a default CSS,\nyou can use your own CSS file.\n\ne.g.\n\n```javascript\nconst path = require('path');\n\nsearchInPage(webview, {\n    customCssPath: path.join(__dirname, 'my_awesome_styles.css')\n});\n```\n\nBelow is a list of `class` property of each parts in search window.\nPlease write your CSS styles for below classes.\n\n| class name              | description                 | element   |\n|-------------------------|-----------------------------|-----------|\n| `inpage-search-body`    | Body of whole search window | `\u003cdiv\u003e`   |\n| `inpage-search-input`   | Query form                  | `\u003cinput\u003e` |\n| `inpage-search-matches` | 'N/M' search count          | `\u003cdiv\u003e`   |\n| `inpage-search-back`    | 'back' button               | `\u003cdiv\u003e`   |\n| `inpage-search-forward` | 'forward' button            | `\u003cdiv\u003e`   |\n| `inpage-search-close`   | 'close' button              | `\u003cdiv\u003e`   |\n\n### Use my own HTML for search window\n\nIf you want to control the whole search window, you can pass a path to your own HTML file.\n\n```javascript\nconst path = require('path');\n\nsearchInPage(webview, {\n    customCssPath: path.join(__dirname, 'my_awesome_styles.css'),\n    customSearchWindowHtmlPath: path.join(__dirname, 'my_awesome_search_window.html')\n});\n```\n\nelectron-in-page-search package injects `\u003cscript\u003e` tag to setup IPC messaging between\na search window `\u003cwebview\u003e` and a renderer process. It finds each elements and\nsets listeners through class names.\n\nSo you need to maintain above class names also in your own search window HTML.\n\n### Lifetime hooks for search\n\n`InPageSearch` instance (returned from `searchInPage`) extends `EventEmitter`.\nIt emits some events on some timings.\nYou can hook them to execute your code at some points.\n\nBelow is a list of hook names.\n\n| hook name     | description                              | listener args                             |\n|---------------|------------------------------------------|-------------------------------------------|\n| 'open'        | On window opened                         | `()`                                      |\n| 'start'       | On in-page search started                | `(query: string)`                         |\n| 'next'        | On finding next match                    | `(query: string, forward: boolean)`       |\n| 'focus-input' | On focusing on search window             | `()`                                      |\n| 'found'       | On some word matched to the search query | `(activeMatch: number, allMatch: number)` |\n\n### Animation for search window\n\nYou can use CSS animation for animation of search window. If you don't want to animate a search window\nwhen the webview is mounted, please use `search-firstpaint` class name as below:\n\n```css\n.electron-in-page-search-window.search-firstpaint {\n  visibility: hidden;\n}\n\n.electron-in-page-search-window.search-inactive {\n  animation-duration: 0.2s;\n  animation-name: yourAwesomeAnimationOnClosing;\n}\n\n.electron-in-page-search-window.search-active {\n  animation-duration: 0.2s;\n  animation-name: yourAwesomeAnimationOnOpening;\n}\n```\n\nThe `search-firstpaint` class will be removed when opening search window at first.\n\n### Preload a search window\n\n`InPageSearch` instance delays creating `\u003cwebview\u003e` element for a search window\nuntil first `openSearchWindow` is called at first.\nThis is better in terms of memory efficiency because `\u003cwebview\u003e` forks a new process.\n\nIf you want to load a search window in advance, please set `preloadSearchWindow: true`\nto the second argument of `searchInPage()` call.\n\n\n\n## License\n\n[Distributed under the MIT License](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Felectron-in-page-search","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frhysd%2Felectron-in-page-search","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frhysd%2Felectron-in-page-search/lists"}