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.

Install

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

Usage

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 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: ''

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

replaceTerm

The initial text used by the replace commands.

Default: ''

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

caseSensitive

Whether the search matches case exactly.

Default: false

FindAndReplace.configure({
  caseSensitive: true,
})

useRegex

Whether searchTerm is treated as a regular expression.

Default: false

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

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

FindAndReplace.configure({
  searchDebounceMs: 0,
})

injectCSS

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

Default: true

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

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

Commands

setSearchTerm()

Set the search term and highlight every match.

editor.commands.setSearchTerm('Tiptap')

setReplaceTerm()

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

editor.commands.setReplaceTerm('Editor')

setCaseSensitive()

Enable or disable case-sensitive matching.

editor.commands.setCaseSensitive(true)

setUseRegex()

Enable or disable regular expression matching.

editor.commands.setUseRegex(true)

setWholeWord()

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

editor.commands.setWholeWord(true)

goToNextResult()

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

editor.commands.goToNextResult()

goToPreviousResult()

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

editor.commands.goToPreviousResult()

replace()

Replace the selected result and select the next available result.

editor.commands.replace()

replaceAll()

Replace every result in the current result set.

editor.commands.replaceAll()

clearSearch()

Clear the search term and remove every result highlight.

editor.commands.clearSearch()

Storage

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

searchTerm

The current search term.

editor.storage.findAndReplace.searchTerm

replaceTerm

The current replacement text.

editor.storage.findAndReplace.replaceTerm

caseSensitive, useRegex, and wholeWord

The current matching options.

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.

editor.storage.findAndReplace.results

currentIndex

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

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.

.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/