---
title: "Find and Replace extension"
description: "Search, highlight, navigate, and replace text in a Tiptap editor with the Find and Replace extension."
canonical_url: "https://tiptap.dev/docs/editor/extensions/functionality/find-and-replace"
---

# Find and Replace extension

Search, highlight, navigate, and replace text in a Tiptap editor with the Find and Replace extension.

The Find and Replace extension searches the document, highlights matches, and provides commands for navigation and replacement. It is headless, so you can build the controls and place them anywhere in your application.

> **Interactive demo:** [FindAndReplace](https://embed.tiptap.dev/preview/Extensions/FindAndReplace)

## Install

```bash
npm install @tiptap/extension-find-and-replace
```

## Usage

```js
import { Editor } from '@tiptap/core'
import FindAndReplace from '@tiptap/extension-find-and-replace'
import StarterKit from '@tiptap/starter-kit'

new Editor({
  extensions: [StarterKit, FindAndReplace],
})
```

See the [custom UI guide](https://tiptap.dev/docs/guides/find-and-replace.md) for complete React and Vue examples.

## Settings

These options set the initial state. Use the commands below to update the search while the editor is running.

### searchTerm

The initial text to search for. In regex mode, this is the regular expression source.

Default: `''`

```js
FindAndReplace.configure({
  searchTerm: 'Tiptap',
})
```

### replaceTerm

The initial text used by the replace commands.

Default: `''`

```js
FindAndReplace.configure({
  replaceTerm: 'Editor',
})
```

### caseSensitive

Whether the search matches case exactly.

Default: `false`

```js
FindAndReplace.configure({
  caseSensitive: true,
})
```

### useRegex

Whether `searchTerm` is treated as a regular expression.

Default: `false`

```js
FindAndReplace.configure({
  useRegex: true,
  searchTerm: 'colou?r',
})
```

Invalid patterns and patterns rejected as unsafe return no results. Regex mode controls matching only: replacement text is inserted literally, so capture references such as `$1` are not expanded.

### wholeWord

Whether to match complete words only. This option is ignored when `useRegex` is enabled.

Default: `false`

```js
FindAndReplace.configure({
  wholeWord: true,
})
```

### searchDebounceMs

The delay, in milliseconds, before `setSearchTerm()` updates the search results. Set this to `0` to update results immediately.

Default: `250`

```js
FindAndReplace.configure({
  searchDebounceMs: 0,
})
```

### injectCSS

Whether to inject the default result highlight styles. Disable this option to provide your own styles.

Default: `true`

```js
FindAndReplace.configure({
  injectCSS: false,
})
```

### injectNonce

The nonce applied to the injected style element. Set this when your Content Security Policy requires a nonce.

Default: `undefined`

```js
FindAndReplace.configure({
  injectNonce: 'your-nonce-here',
})
```

## Commands

### setSearchTerm()

Set the search term and highlight every match.

```js
editor.commands.setSearchTerm('Tiptap')
```

### setReplaceTerm()

Set the text used by `replace()` and `replaceAll()`.

```js
editor.commands.setReplaceTerm('Editor')
```

### setCaseSensitive()

Enable or disable case-sensitive matching.

```js
editor.commands.setCaseSensitive(true)
```

### setUseRegex()

Enable or disable regular expression matching.

```js
editor.commands.setUseRegex(true)
```

### setWholeWord()

Enable or disable whole-word matching. This has no effect while regex mode is enabled.

```js
editor.commands.setWholeWord(true)
```

### goToNextResult()

Select the next result. Navigation wraps from the final result to the first result.

```js
editor.commands.goToNextResult()
```

### goToPreviousResult()

Select the previous result. Navigation wraps from the first result to the final result.

```js
editor.commands.goToPreviousResult()
```

### replace()

Replace the selected result and select the next available result.

```js
editor.commands.replace()
```

### replaceAll()

Replace every result in the current result set.

```js
editor.commands.replaceAll()
```

### clearSearch()

Clear the search term and remove every result highlight.

```js
editor.commands.clearSearch()
```

## Storage

The extension keeps its current state in `editor.storage.findAndReplace`.

### searchTerm

The current search term.

```js
editor.storage.findAndReplace.searchTerm
```

### replaceTerm

The current replacement text.

```js
editor.storage.findAndReplace.replaceTerm
```

### caseSensitive, useRegex, and wholeWord

The current matching options.

```js
editor.storage.findAndReplace.caseSensitive
editor.storage.findAndReplace.useRegex
editor.storage.findAndReplace.wholeWord
```

### results

The matches in document order. Every result has `from` and `to` ProseMirror positions.

```js
editor.storage.findAndReplace.results
```

### currentIndex

The index of the selected result, or `null` when no result is selected.

```js
editor.storage.findAndReplace.currentIndex
```

## Search behavior

Matches update when the document or a search option changes. A match can span text nodes with different marks, but never crosses a textblock or a non-text inline node such as a hard break or mention.

`replaceAll()` replaces the matches that exist when the command runs. If the replacement text also matches the search, those new matches remain in storage after the transaction.

## Styling results

By default, results have a yellow highlight and the selected result has an orange highlight. Disable `injectCSS` to replace these styles.

```css
.find-and-replace-result {
  background-color: rgb(255 225 0 / 0.4);
}

.find-and-replace-result-current {
  background-color: rgb(255 165 0 / 0.55);
}
```

## Source code

[packages/extension-find-and-replace/](https://github.com/ueberdosis/tiptap/tree/main/packages/extension-find-and-replace/)