@codemirror/autocomplete

@codemirror/autocomplete is the official autocompletion package for CodeMirror 6, the in-browser code editor toolkit built by Marijn Haverbeke. It supplies the state, view, and tooltip logic needed to show a completion popup as users type, merging one or more registered completion sources into a single ranked list with fuzzy matching, sectioning, and configurable keybindings.

Beyond raw completion, the package ships snippet support (tab-through placeholder fields), automatic bracket and quote closing, and a small set of composable helpers (ifIn, ifNotIn, completeFromList) for scoping completion sources to specific syntax contexts. Language packages across the CodeMirror ecosystem — for JavaScript, Python, SQL, CSS, and more — depend on it to provide language-aware suggestions.

What You Get

• An autocompletion() extension with configurable activation, keymap, and tooltip rendering
• Fuzzy and strict matching engines that score and rank completions by relevance
• A snippet system with tab-stop navigation and field editing
• An automatic bracket and quote closing extension
• Composable source helpers — completeFromList, ifIn, ifNotIn, completeAnyWord

Common Use Cases

• Wiring language-aware code completion into a CodeMirror-based IDE or code playground
• Providing word-based completion for plain-text or markdown editors
• Building snippet-driven scaffolding for inserting boilerplate code
• Adding bracket and quote auto-closing to any CodeMirror 6 editor instance

Under The Hood

Architecture — The package layers cleanly: state.ts owns the completionState StateField that tracks ActiveSource objects (one per completion source) through Inactive/Pending/Result transitions and rebuilds a CompletionDialog whenever a transaction requires it; tooltip.ts renders the popup via CodeMirror’s showTooltip facet; completion.ts defines the public Completion/CompletionContext/CompletionResult contracts and helpers like completeFromList, ifIn, ifNotIn, and insertCompletionText; filter.ts implements the FuzzyMatcher/StrictMatcher scoring engines consumed by state.ts’s sortOptions; snippet.ts and closebrackets.ts are self-contained sibling extensions composed into the top-level autocompletion() extension array in index.ts. Everything is threaded through CodeMirror’s Facet/StateField/StateEffect primitives rather than an autocomplete-specific event bus, so the package is really a set of pure reducers over EditorState/Transaction objects.

Tech Stack — Pure TypeScript (100% by GitHub’s language breakdown), compiled via the shared @codemirror/buildhelper devDependency into ESM (dist/index.js) and CJS (dist/index.cjs) builds with bundled .d.ts types. Runtime dependencies are exclusively sibling CodeMirror packages — @codemirror/state, @codemirror/view, @codemirror/language — plus @lezer/common for syntax-tree access, keeping the dependency graph entirely first-party with zero third-party runtime deps.

Code Quality — test/webtest-autocomplete.ts defines a purpose-built Runner class that spins up a real EditorView per test case and asserts against live completion state rather than mocking — a heavier-weight but higher-fidelity style of testing for editor behavior. Source files are consistently documented with /// doc comments consumed by CodeMirror’s own doc-generation tooling, naming is terse but consistent with the rest of the CodeMirror 6 codebase, and the code favors immutable value classes (ActiveSource, CompletionDialog, Option) updated via reducer-style .map()/.update() methods over mutation. No explicit try/catch is visible in the reviewed files; failures in async completion sources are expected to surface as rejected promises rather than being caught internally.

API Design — The public surface is small and deliberately composable: one extension factory (autocompletion(config)), a handful of pure helper functions (completeFromList, ifIn/ifNotIn, completeAnyWord) for building CompletionSource functions, and read-only accessors (completionStatus, currentCompletions, selectedCompletion) for host applications to introspect state. Wiring a working autocomplete requires only the autocompletion() extension plus a source via language data or the override config option. Every exported symbol carries a doc comment with cross-links, and the CompletionSource/CompletionResult contract cleanly separates synchronous simple cases (a fixed option list) from async/incremental ones (validFor, update, map) without forcing all consumers to deal with that complexity upfront.