Chrome-like findbar for your Electron application

Installation

Install the electron-findbar package via npm:

npm install electron-findbar

Overview

The electron-findbar is a BrowserWindow component designed to emulate the Chrome findbar layout, leveraging the webContents.findInPage method to navigate through matches. Inter-process communication (IPC) is used for interaction between the main and renderer processes.

Memory Usage

To optimize memory usage, the Findbar window is created only when the findbar is open. The implementation is lightweight, including only essential code.

Usage

All public methods are documented with JSDoc and can be referenced during import.

Importing the Findbar

To import the Findbar class:

const Findbar = require('electron-findbar')

Creating the Findbar Instance

You can pass a BrowserWindow instance as a single parameter to use it as the parent window. The BrowserWindow.WebContents will be used as the findable content:

const findbar = new Findbar(browserWindow)

Alternatively, you can provide a custom WebContents as the second parameter. In this case, the first parameter can be any BaseWindow, and the second parameter will be the findable content:

const findbar = new Findbar(baseWindow, customWebContents)

Configuring the Findbar

You can customize the Findbar window options using the setWindowOptions method:

findbar.setWindowOptions({ movable: true, resizable: true, alwaysOnTop: true })

To handle the Findbar window directly after it is opened, use the setWindowHandler method:

findbar.setWindowHandler(win => {
    win.setVisibleOnAllWorkspaces(true, { visibleOnFullScreen: true })
});

The findbar has a default position handler which moves the findbar to the top-right corner. To change the position handler, use the setPositionHandler method. The position handler is called when the parent window moves or resizes and provides both the parent and findbar bounds as parameters.

findbar.setPositionHandler((parentBounds, findbarBounds) => ({
    x: parentBounds.x + parentBounds.width - findbarBounds.width - 20,
    y: parentBounds.y - ((findbarBounds.height / 4) | 0)
}))

Opening the Findbar

The Findbar is a child window of the BaseWindow passed during construction. To open it use:

findbar.open()

Finding Text in the Page

Once open, the Findbar appears by default in the top-right corner of the parent window and can be used without additional coding. Alternatively, you can use the following methods to trigger findInPage and navigate through matches in the main process:

/**
 * Retrieve the last queried value.
 */
getLastValue()

/**
 * Initiate a request to find all matches for the specified text on the page.
 * @param {string} text - The text to search for.
 */
startFind(text)

/**
 * Select the previous match, if available.
 */
findPrevious()

/**
 * Select the next match, if available.
 */
findNext()

/**
 * Stop the find request.
 */
stopFind()

Closing the Findbar

When the Findbar is closed, its window is destroyed to free memory resources. Use the following method to close the Findbar:

findbar.close()

A new internal window will be created the next time the open method is called. There is no need to instantiate another Findbar for the same parent window.

Quick Example

Here is a quick example demonstrating how to use the electron-findbar:

const { app, BrowserWindow } = require('electron')
const Findbar = require('electron-findbar')

app.whenReady().then(() => {  
  const window = new BrowserWindow()
  window.loadURL('https://github.com/ECRomaneli/electron-findbar')

  // Create and configure the Findbar object
  const findbar = new Findbar(window)

  // [OPTIONAL] Customize window options
  findbar.setWindowOptions({ movable: true, resizable: true })

  // [OPTIONAL] Handle the window object when the Findbar is opened
  findbar.setWindowHandler(win => {
    win.webContents.openDevTools()
  })

  // Open the Findbar
  findbar.open()
})

IPC Events

As an alternative, the findbar can be controlled using IPC events in the renderer process of the WebContents provided during the findbar construction.

ipcRenderer

If the contextIsolation is enabled, the electron-findbar/remote will not be available, but the IPC events can be used directly through the preload script:

const $remote = (ipc => ({
    getLastText: async () => ipc.invoke('electron-findbar/last-text'),
    inputChange: (value) => { ipc.send('electron-findbar/input-change', value) },
    previous: () => { ipc.send('electron-findbar/previous') },
    next: () => { ipc.send('electron-findbar/next') },
    open: () => { ipc.send('electron-findbar/open') },
    close: () => { ipc.send('electron-findbar/close') },
})) (require('electron').ipcRenderer)

$remote.open()
$remote.inputChange('findIt')

Remote module

With the contextIsolation disabled, the remote library is available to use:

const FindbarRemote = require('electron-findbar/remote')

FindbarRemote.open()
FindbarRemote.inputChange('findIt')

Author

Created by Emerson Capuchi Romaneli (@ECRomaneli).

License

This project is licensed under the MIT License.