@bhsd/codemirror-stickyscroll

VS Code / Monaco-style sticky scroll (sticky lines) for CodeMirror 6.

This is a fork of @fazelstudio/codemirror-stickyscroll that adds support for foldService, which makes it compatible with legacy StreamParser languages that register folding. This personal fork also removes some unused features.

Sticky lines keep the opening lines of the enclosing scopes (function, class, if/loop blocks, …) pinned at the top of the editor while you scroll — exactly like VS Code's sticky scroll, but built purely as an external CodeMirror 6 extension (no fork of @codemirror/*).

Features

• Per-pixel updates — a native scroll listener + requestAnimationFrame throttle keeps the bar glued to the scroll position; no "jumpy" updates.
• Click-to-jump with margin compensation — clicking a sticky line scrolls the target line to the top plus the current bar height, so the line you jump to is never hidden behind the bar. Keyboard (Enter/Space) + role="button" for a11y.
• Reuses the consumer's theme — the bar re-highlights lines through the active highlight styles of the editor (highlightingFor), or clones the already-rendered DOM line when available. The package never registers its own syntaxHighlighting(...).
• Language-agnostic — detection is based on foldNodeProp or foldService from @codemirror/language (the fold services / fold node props that every @codemirror/lang-* already registers). It includes a smart, generic denylist that works across multiple languages (JS/TS, Python, Rust, Go, etc.) out of the box, and gracefully handles data languages like JSON.
• Gutter alignment, horizontal sync, RTL, resize-proof — line numbers are aligned with the real gutter (width tracked via ResizeObserver), the bar follows horizontal scroll, and it reacts to font/zoom/resize changes.
• Zero runtime deps — peer dependencies only.

Installation

npm install @bhsd/codemirror-stickyscroll

The following are peer dependencies (already present in any project that has a working CodeMirror 6 editor):

| Package | Minimum | | --- | --- | | @codemirror/view | ^6.3.0 | | @codemirror/state | ^6.0.0 | | @codemirror/language | ^6.0.0 |

API

stickyScroll(options?: StickyScrollOptions): Extension

interface StickyScrollOptions {
  /** Maximum sticky lines shown at once (dynamically clamped to ~40% of editor height). Default: 4 */
  maxStickyLines?: number;
  /** Minimum lines a scope must span to become sticky. Default: 6 */
  minBlockLines?: number;
  /**
   * Denylist predicate: return true to never pin a foldable node of that type.
   * Defaults to `defaultExcludeNode` (imports + data literals + comments).
   * It uses exact node names for JS/TS and generic regex patterns for other
   * languages, while automatically bypassing the literal denylist for JSON.
   */
  excludeNode?: (nodeName?: string, langName?: string, ownerName?: string) => boolean;
  /** Extra CSS class(es) for the bar container. */
  class?: string;
}

Re-exports

import {
  stickyScroll,
  defaultExcludeNode,       // default denylist implementation
  stickyScrollEffect,       // StateEffect to trigger a re-render (e.g. after theme change)
  type StickyScrollOptions,
} from "@bhsd/codemirror-stickyscroll";

Styling

The bar is layout-only by default and always follows the editor's own theme (token colors, background). You can restyle it with CSS.

Per-row hooks:

| Class | Purpose | | --- | --- | | .cm-stickyscroll-container | the overlay bar | | .cm-stickyscroll-line | one breadcrumb row | | .cm-stickyscroll-line:hover | hover highlight | | .cm-stickyscroll-line.cm-stickyscroll-current | block containing the cursor | | .cm-stickyscroll-gutter | line-number cell | | .cm-stickyscroll-code | code column (horizontally synced) |

How it works

1. Detect the top line — view.lineBlockAtHeight(clientTop - documentTop).
2. Walk the syntax tree — from syntaxTree(state).resolveInner(topPos, 0) up through node.parent.
3. A scope qualifies when its opening line is foldable, its fold anchor node is not denylisted, and it spans ≥ minBlockLines.
4. Render — a ViewPlugin owns an absolutely-positioned overlay (position: absolute; top: 0 inside view.dom), updated per-frame from the native scroll event; line numbers align with the real gutter; token colors come from the consumer's active highlighters.

The DOM overlay (rather than the Panel API / showPanel) is what makes the bar behave like Monaco: it never pushes the content down (no reflow) and it can be updated per-pixel, which panels cannot (panels only re-render on ViewUpdate, not on pure scroll).

Language support

Works out of the box with any @codemirror/lang-* (or community grammar) that registers folding — JS/TS, Rust, Python, Java, Go, C#, etc.

License

MIT — © Zulfazli (Fazelllyyy) · https://github.com/fazelllyyy