prosemirror-search

prosemirror-search

[ WEBSITE | ISSUES | FORUM | GITTER ]

This module defines an API for searching through ProseMirror documents, search/replace commands, and a plugin that highlights the matches of a given search query.

When using this module, you should either load style/search.css into your page, or define your own styles for the ProseMirror-search-match (search match) and ProseMirror-active-search-match (the active match) classes.

The project page has more information, a number of examples and the documentation.

This code is released under an MIT license. There's a forum for general discussion and support requests, and the Github bug tracker is the place to report issues.

We aim to be an inclusive, welcoming community. To make that explicit, we have a code of conduct that applies to communication around the project.

API

• search(options?: {initialQuery?: SearchQuery, initialRange?: {from: number, to: number}} = {}) → Plugin
  Returns a plugin that stores a current search query and searched range, and highlights matches of the query.

class SearchQuery

• new SearchQuery(config: Object)
  Create a query object.

  • config: Object

    • search: string
      The search string.

    • caseSensitive?: boolean
      Controls whether the search should be case-sensitive.

    • literal?: boolean
      By default, string search will replace \n, \r, and \t in the query with newline, return, and tab characters. When this is set to true, that behavior is disabled.

    • regexp?: boolean
      When true, interpret the search string as a regular expression.

    • replace?: string
      The replace text.

    • wholeWord?: boolean
      Enable whole-word matching.

• search: string
  The search string (or regular expression).

• caseSensitive: boolean
  Indicates whether the search is case-sensitive.

• literal: boolean
  By default, string search will replace \n, \r, and \t in the query with newline, return, and tab characters. When this is set to true, that behavior is disabled.

• regexp: boolean
  When true, the search string is interpreted as a regular expression.

• replace: string
  The replace text, or the empty string if no replace text has been given.

• valid: boolean
  Whether this query is non-empty and, in case of a regular expression search, syntactically valid.

• wholeWord: boolean
  When true, matches that contain words are ignored when there are further word characters around them.

• eq(other: SearchQuery) → boolean
  Compare this query to another query.

• findNext(state: EditorState, from?: number = 0, to?: number = state.doc.content.size) → SearchResult
  Find the next occurrence of this query in the given range.

• findPrev(state: EditorState, from?: number = state.doc.content.size, to?: number = 0) → SearchResult
  Find the previous occurrence of this query in the given range. Note that, if to is given, it should be less than from.

• getReplacements(state: EditorState, result: SearchResult) → {from: number, to: number, insert: Slice}[]
  Get the ranges that should be replaced for this result. This can return multiple ranges when this.replace contains $1/$&-style placeholders, in which case the preserved content is skipped by the replacements.

  Ranges are sorted by position, and from/to positions all refer to positions in state.doc. When applying these, you'll want to either apply them from back to front, or map these positions through your transaction's current mapping.

interface SearchResult

A matched instance of a search query. match will be non-null only for regular expression queries.

• from: number

• to: number

• match: RegExpMatchArray

These functions can be used to manipulate the active search state:

• getSearchState(state: EditorState) → {query: SearchQuery, range: {from: number, to: number}}
  Get the current active search query and searched range. Will return undefined is the search plugin isn't active.

• setSearchState(tr: Transaction, query: SearchQuery, range?: {from: number, to: number} = null) → Transaction
  Add metadata to a transaction that updates the active search query and searched range, when dispatched.

• getMatchHighlights(state: EditorState) → DecorationSet
  Access the decoration set holding the currently highlighted search matches in the document.

Commands

• findNext: Command
  Find the next instance of the search query after the current selection and move the selection to it.

• findPrev: Command
  Find the previous instance of the search query and move the selection to it.

• findNextNoWrap: Command
  Find the next instance of the search query and move the selection to it. Don't wrap around at the end of document or search range.

• findPrevNoWrap: Command
  Find the previous instance of the search query and move the selection to it. Don't wrap at the start of the document or search range.

• replaceNext: Command
  Replace the currently selected instance of the search query, and move to the next one. Or select the next match, if none is already selected.

• replaceNextNoWrap: Command
  Replace the next instance of the search query. Don't wrap around at the end of the document.

• replaceCurrent: Command
  Replace the currently selected instance of the search query, if any, and keep it selected.

• replaceAll: Command
  Replace all instances of the search query.

Changelog

1.0.0 (2024-07-14)

New Features

The new filter query option makes the query skip matches for which a predicate returns false.

Bug Fixes

Fix an issue where replacement that reused parts of the match inside an inline node with content preserved the wrong pieces of content.