@codemirror/search

@codemirror/search is the official search extension for CodeMirror 6, the extensible in-browser code editor. It adds an interactive search-and-replace panel, plain-string and regular-expression matching, whole-word and case-sensitive options, and live highlighting of the current selection’s occurrences across the document.

Beyond the ready-made panel, the package exposes composable editor commands and two standalone match-iterator classes — SearchCursor and RegExpCursor — that you can drive directly from your own UI or keymaps. It follows CodeMirror’s facet-and-extension model, so search state integrates cleanly with the rest of your editor configuration.

What You Get

• A drop-in search panel with find, replace, replace-all, case-sensitivity, whole-word, and regular-expression toggles
• A ready-made searchKeymap plus individual commands (findNext, findPrevious, replaceNext, replaceAll, openSearchPanel, gotoLine) you can bind however you like
• SearchCursor and RegExpCursor iterator classes for scanning document text by string or regex, usable independently of the panel
• Live selection-match highlighting via highlightSelectionMatches and multi-cursor selectNextOccurrence
• An immutable SearchQuery value object and facet-based configuration for panel placement and default match options

Common Use Cases

• Adding Ctrl/Cmd-F find-and-replace to a CodeMirror-based code or text editor in a web app
• Building a bespoke search UI while reusing the underlying cursors and commands
• Highlighting every occurrence of the current selection as the user moves through a document
• Implementing editor-style ‘select next occurrence’ multi-cursor editing

Under The Hood

Architecture

The entry point src/search.ts exposes search(config?), which returns a CodeMirror Extension combining a searchConfigFacet with the core search extensions. Search state lives in a StateField mutated through StateEffects such as setSearchQuery, while editor Commands (findNext, findPrevious, replaceNext, replaceAll, openSearchPanel, closeSearchPanel) act on the EditorView/EditorState. The UI is a CodeMirror Panel shown via showPanel and assembled with the tiny crelt DOM helper. Text matching is cleanly separated into two iterator classes: SearchCursor (src/cursor.ts) performs buffered, NFKD-normalized plain-string scanning over a TextIterator, and RegExpCursor (src/regexp.ts) does line-oriented regular-expression matching. src/selection-match.ts supplies highlightSelectionMatches as a ViewPlugin that emits a DecorationSet, and src/goto-line.ts adds the go-to-line command. The result is a well-layered design: pure iterators feed a SearchQuery model, which drives state and commands, which the view renders.

Tech Stack

The package is written entirely in TypeScript and depends only on @codemirror/state (^6), @codemirror/view (^6.37), and crelt (^1) for DOM construction. It is ESM-first but ships dual builds (dist/index.js and dist/index.cjs) with bundled type declarations and sideEffects: false for tree-shaking. Builds run through @codemirror/buildhelper (cm-buildhelper) and tests through cm-runtests, keeping the dependency and tooling surface deliberately minimal.

Code Quality

The test/ directory covers the core primitives — test-cursor.ts, test-query.ts, and test-selection-match.ts — exercising string/regex matching, query parsing, and selection highlighting. Source files are small and focused, use strict TypeScript with readonly fields and explicit iterator interfaces, and carry /// doc comments on every public API that generate the reference docs. Regex validity is guarded via validRegExp. Test coverage concentrates on the matching engine rather than the panel/command UI.

API Design Developer experience is excellent within the CodeMirror ecosystem: a single search(config?) extension is the entry point, configured through a typed SearchConfig (panel placement, default case-sensitivity, literal, whole-word, regexp, custom createPanel, and scrollToMatch). Commands are exported individually so they compose into custom keymaps, SearchQuery is an immutable value object, and the SearchCursor/RegExpCursor classes are usable standalone outside the editor. Naming is consistent with CodeMirror 6 conventions; the main cost is the boilerplate required to author a fully custom panel.