# Search and replace document text

> Enable document-aware search, move through matches, and choose which search controls SuperDoc renders.



Use the built-in search surface to find text across the open document without leaving the Editor.

## Try search and replace [#try-search-and-replace]

Expand the Editor and open Search from the toolbar. The sample has three short pages built for these checks:

1. Search for `Client` and confirm that there are eight matches.
2. Move through the results with Previous and Next, and watch the Editor scroll between pages.
3. Turn on Match case and confirm that the count changes to seven.
4. Turn Match case off, then replace one result with `Customer`.
5. Search for `Legacy` with **Tracked deletions** set to **Exclude** and confirm that there are no matches.
6. Set **Tracked deletions** to **Include**, reopen Search, and search for `Legacy` again. The pending deletion is the
   only match.

> **Interactive editor: Try search and replace**
>
> Sample: [open the fixture](/fixtures/search-sample.docx).
>
> Preset: `search`.
>
> Search configurations available in the interactive Editor:
>
> - **Mode — `documentMode`:** Editing allows replacement. Search remains available in Viewing, but replace controls are hidden.
> - **Replace controls — `ui.search.replaceControls`:** choose Show or Hide. Hide removes the built-in replacement row in every document mode.
> - **Tracked deletions — `ui.search.includeTrackedDeletions`:** choose Exclude or Include. The sample has one pending deletion containing `Legacy`.
>
> The three-page fixture has eight case-insensitive `Client` matches and seven case-sensitive matches. `Legacy` has zero matches when tracked deletions are excluded and one when they are included. Moving between results scrolls the Editor to each match. Changing a Search startup option recreates the Editor from its current DOCX. Document edits and document mode remain; the active search resets.
>
> Local DOCX selection: disabled.


Set **Replace controls** to **Hide**. Search remains available, but the replacement row disappears. The demo reloads the
current document when you change either option because they configure Search at startup. Document edits remain, while
the active search resets.

Switch to Viewing after the search. The matches and navigation controls remain available, while the replace controls
disappear because Viewing cannot change the document.

## Enable built-in search [#enable-built-in-search]

Continue with `/sample.docx` from the [Quickstart](/editor/quickstart), then enable the search surface:

**Vanilla — `src/main.ts`**

```ts
import { SuperDoc } from 'superdoc';
import 'superdoc/style.css';

const superdoc = new SuperDoc({
  selector: '#editor',
  document: '/sample.docx',
  ui: {
    toolbar: { container: '#toolbar' },
    search: true,
  },
});

window.addEventListener('beforeunload', () => superdoc.destroy());

```

**React — `src/App.tsx`**

```tsx
import { SuperDocEditor, type SuperDocEditorProps } from '@superdoc/react';
import '@superdoc/react/style.css';

const editorConfig = {
  ui: {
    search: true,
  },
} satisfies Pick<SuperDocEditorProps, 'ui'>;

export default function App() {
  return <SuperDocEditor document='/sample.docx' ui={editorConfig.ui} />;
}

```


Vanilla also needs separate toolbar and Editor mounts:

```html
<div id="toolbar"></div>
<div id="editor" style="height: 70vh"></div>

<script type="module" src="/src/main.ts"></script>

```

`ui: { search: true }` connects the toolbar Search button and `Ctrl+F` or `Command+F` to the same document search.
Without it, the browser keeps its native page search shortcut.

Open Search with both methods. Search for `Client` and confirm that each method shows the same match count and active
result.

## Configure the search surface [#configure-the-search-surface]

Choose a group, then choose a field. Each entry shows its type, default, and a configuration fragment you can copy.

### Behavior

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `replaceControls` | `boolean` | `true` | Optional | Show replace controls (default: true). This changes the built-in UI only; it does not authorize or disable `superdoc.ui.search.replace()`. | Show replace controls (default: true). This changes the built-in UI only; it does not authorize or disable `superdoc.ui.search.replace()`. | — |
| `includeTrackedDeletions` | `boolean` | `false` | Optional | Include text from pending tracked deletions in each search (default: false). | Include text from pending tracked deletions in each search (default: false). | — |

### Position & size

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `floating.placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left" \| "top-center" \| "bottom-center"` | `'top-right'` | Optional | Position preset (default: `'top-right'`). Explicit insets override it. | Position preset (default: `'top-right'`). Explicit insets override it. | — |
| `floating.top` | `string \| number` | — | Optional | Top inset in pixels or as a CSS length. | Top inset in pixels or as a CSS length. | — |
| `floating.right` | `string \| number` | — | Optional | Right inset in pixels or as a CSS length. | Right inset in pixels or as a CSS length. | — |
| `floating.bottom` | `string \| number` | — | Optional | Bottom inset in pixels or as a CSS length. | Bottom inset in pixels or as a CSS length. | — |
| `floating.left` | `string \| number` | — | Optional | Left inset in pixels or as a CSS length. | Left inset in pixels or as a CSS length. | — |
| `floating.width` | `string \| number` | `420` | Optional | Surface width in pixels or as a CSS length. | Surface width in pixels or as a CSS length. | — |
| `floating.maxWidth` | `string \| number` | — | Optional | Maximum surface width in pixels or as a CSS length. | Maximum surface width in pixels or as a CSS length. | — |
| `floating.maxHeight` | `string \| number` | — | Optional | Maximum surface height in pixels or as a CSS length. | Maximum surface height in pixels or as a CSS length. | — |

### Focus

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `floating.autoFocus` | `boolean` | `true` | Optional | Focus the find input when the surface opens (default: true). | Focus the find input when the surface opens (default: true). | — |
| `floating.closeOnOutsidePointerDown` | `boolean` | `false` | Optional | Close the surface when a pointer press occurs outside it (default: false). | Close the surface when a pointer press occurs outside it (default: false). | — |

### Text

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `strings.findPlaceholder` | `string` | `'Find'` | Optional | Input placeholder for the find field. | Input placeholder for the find field. | — |
| `strings.replacePlaceholder` | `string` | `'Replace'` | Optional | Input placeholder for the replace field. | Input placeholder for the replace field. | — |
| `strings.noResults` | `string` | `'No results'` | Optional | Text shown when there are no matches. | Text shown when there are no matches. | — |
| `strings.previousMatchTitle` | `string` | `'Previous match (Shift+Enter)'` | Optional | Tooltip for the previous-match button. | Tooltip for the previous-match button. | — |
| `strings.nextMatchTitle` | `string` | `'Next match (Enter)'` | Optional | Tooltip for the next-match button. | Tooltip for the next-match button. | — |
| `strings.closeTitle` | `string` | `'Close (Escape)'` | Optional | Tooltip for the close button. | Tooltip for the close button. | — |
| `strings.replace` | `string` | `'Replace'` | Optional | Replace button text. | Replace button text. | — |
| `strings.replaceAll` | `string` | `'All'` | Optional | Replace-all button text. | Replace-all button text. | — |
| `strings.toggleReplaceTitle` | `string` | `'Toggle replace'` | Optional | Tooltip for the button that expands or collapses replace controls. | Tooltip for the button that expands or collapses replace controls. | — |
| `strings.matchCase` | `string` | `'Aa'` | Optional | Match case toggle text. | Match case toggle text. | — |
| `strings.ignoreDiacritics` | `string` | `'ä≡a'` | Optional | Ignore diacritics toggle text. | Ignore diacritics toggle text. | — |
| `strings.regex` | `string` | `'.*'` | Optional | Regex toggle text. | Regex toggle text. | — |
| `strings.invalidPattern` | `string` | `'Invalid pattern'` | Optional | Inline error shown when the regex pattern is invalid or unsafe. | Inline error shown when the regex pattern is invalid or unsafe. | — |

### Accessibility

| Field | Type | Default | Status | Summary | API details | Guide |
| --- | --- | --- | --- | --- | --- | --- |
| `strings.findAriaLabel` | `string` | `'Find text'` | Optional | Accessible label for the find input. | Accessible label for the find input. | — |
| `strings.replaceAriaLabel` | `string` | `'Replace text'` | Optional | Accessible label for the replace input. | Accessible label for the replace input. | — |
| `strings.previousMatchAriaLabel` | `string` | `'Previous match'` | Optional | Accessible label for previous match button. | Accessible label for previous match button. | — |
| `strings.nextMatchAriaLabel` | `string` | `'Next match'` | Optional | Accessible label for next match button. | Accessible label for next match button. | — |
| `strings.closeAriaLabel` | `string` | `'Close find and replace'` | Optional | Accessible label for close button. | Accessible label for close button. | — |
| `strings.toggleReplaceAriaLabel` | `string` | `'Toggle replace'` | Optional | Accessible label for toggle replace button. | Accessible label for toggle replace button. | — |
| `strings.matchCaseAriaLabel` | `string` | `'Match case'` | Optional | Accessible label for match case toggle. | Accessible label for match case toggle. | — |
| `strings.ignoreDiacriticsAriaLabel` | `string` | `'Ignore diacritics'` | Optional | Accessible label for ignore diacritics toggle. | Accessible label for ignore diacritics toggle. | — |
| `strings.regexAriaLabel` | `string` | `'Use regular expression'` | Optional | Accessible label for the regex toggle. | Accessible label for the regex toggle. | — |


`replaceControls: false` changes only the built-in UI. It does not disable `superdoc.ui.search.replace()` or enforce a
permission. Keep application-owned replacement controls synchronized with `canReplace` from
`superdoc.ui.search.observe()`.

Search also supports match case and regular expressions. Invalid regular expressions show an error instead of running a
partial search.

Finding a pending deletion does not restore, accept, or reject it. It only adds that text to the current search results.

Search highlights and the active match are temporary Editor state. Replacements change the document, so use the save
flow from [Load and save](/editor/load-and-save-documents) to persist them.

Use [custom search controls](/editor/custom-ui/search) when your application should render the search surface. Use
[Document API queries](/document-api/query-content) when code needs document targets instead of a visual search session.