Use the Find interface

The editor includes a built-in Find bar for searching the current document. It’s ready after setup. If you haven’t set it up yet, refer to the getting started guide.

This guide covers Find bar keyboard controls, the editor.find API, toolbar integration, and search scope. The editor.find namespace is available from 1.19.0, the built-in find toolbar item from 1.20.0, and programmatic find results with portable locations from 1.22.0.

The examples omit error handling, so add error handling before you use this code in production.

Find behavior and keyboard controls

Keyboard access to the Find bar doesn’t need toolbar configuration:

• Control/Command-F opens the bar and focuses its input.
• Control/Command-F presets the query with the first line of selected text.
• Enter moves to the next match, and Shift-Enter moves to the previous match. Both wrap around the end of the document.
• Escape closes the bar and returns focus to the document when the input has focus.
• The bar includes previous-match, next-match, and close buttons. The navigation buttons stay disabled while the query has no matches.

The bar reports the current position and total, such as 3 of 12. It highlights every match and applies a stronger highlight to the current match. Moving to a match selects it in the document and scrolls it into view.

To expose Find in a custom toolbar, add the built-in find item to the toolbar configuration. Refer to the actions and toolbar guide for the complete configuration.

Matching runs asynchronously, so highlights appear shortly after the query changes. While the bar stays open, edits to the document update the matches. Closing the bar clears the highlights.

Open and close the Find bar with the programmatic API

Use editor.find.open() to open the bar and focus its input:

editor.find.open();

Pass query to preset the search text. The query replaces the current bar text:

editor.find.open({ query: 'hello' });

Use editor.find.close() to close the bar and clear the match highlights:

editor.find.close();

Both methods do nothing when no state changes. Calling open() with the same query while the bar is already open is a no-op, and it doesn’t refocus the input. Calling close() while the bar is already closed is also a no-op.

The bar keeps its query after closing, so open() without a query reopens the previous search text. That query lives in memory for the editor instance lifetime and isn’t restored after a page reload. Calling editor.setCurrentDocument() closes the bar and clears the query, while the editor.find handle stays valid.

Connect Find to custom application chrome

Applications that replace the editor chrome can drive the Find bar from their own button. Read editor.find.getState() on each click and branch on open:

const editor = await docAuthSystem.createEditor(
  document.getElementById('editor'),
);

const findButton = document.getElementById('find-toggle');

findButton.addEventListener('click', () => {
  if (editor.find.getState().open) {
    editor.find.close();
    return;
  }

  editor.find.open();
});

The corresponding HTML for the button could look like this:

<button id="find-toggle" type="button">Find</button>

Read the state at the moment of the click instead of tracking a Boolean in the host application. The bar also opens with Control/Command-F and closes with Escape or its close button, and neither route passes through host code. The editor emits no event for Find state changes, so a host-tracked flag drifts out of synchronization with the bar.

What the Find bar searches

The bar searches the whole document, not only the visible page. It covers:

• Body text, including text in tables and nested tables
• Text inside shapes and text boxes
• Footnote and endnote text
• Headers and footers, including the tables and shapes they contain

Header and footer variants are searched only when the current layout renders them. A first-page or even-page variant that the document defines but never renders produces no matches.

The bar matches literal text case-insensitively within a single paragraph. It doesn’t search comment text. To match case-sensitively, match a pattern, or replace matches, use the transaction-based programmatic API. Refer to the find and replace guide for searchText() and replaceText().

Search without opening the Find bar

Use editor.find.search() to search for literal text without opening or changing the Find bar. Each result can select and reveal its match, and it includes a portable location for navigation or temporary highlighting.

For a full example with editor.navigateTo() and editor.addVisualHighlight(), refer to the document locations guide.

Learn more

Refer to these guides for related Find workflows:

• Document locations — Search without opening the Find bar. This guide also covers result navigation and visual highlights.
• Find and replace — Search and replace text with the programmatic API.
• Actions and toolbar — Add Find to a custom toolbar.
• Document Authoring API reference