@fazelstudio/codemirror-overview-ruler

A generic, reusable Overview Ruler for CodeMirror 6.

Overview

An Overview Ruler is a narrow visual ruler aligned to the right (or left) side of the editor's scrollable viewport that displays compact markers representing document ranges.

This is different from:

• Column rulers - vertical lines at specific column positions
• Minimap - a condensed text preview of the document
• Gutters - per-line decorations on the side

The Overview Ruler aggregates arbitrary document-range markers from multiple providers and renders them as a performant, themeable overview map.

Installation

npm install @fazelstudio/codemirror-overview-ruler

Usage

Basic

import { EditorView } from "@codemirror/view";
import { EditorState } from "@codemirror/state";
import { overviewRuler, overviewRulerMarkers } from "@fazelstudio/codemirror-overview-ruler";

const view = new EditorView({
  state: EditorState.create({
    doc: "Your code here",
    extensions: [
      overviewRuler(),
      overviewRulerMarkers.of([
        { from: 10, to: 30, type: "error" },
        { from: 50, to: 70, type: "warning" },
      ]),
    ],
  }),
  parent: document.body,
});

Multiple Providers

extensions: [
  overviewRuler(),

  // Lint markers
  overviewRulerMarkers.of(lintMarkers),

  // Search markers
  overviewRulerMarkers.of(searchMarkers),

  // Git change markers
  overviewRulerMarkers.of(gitMarkers),
]

Configuration

overviewRuler({
  position: "right",  // or "left"
  width: 10,           // ruler width in pixels
  clickToNavigate: true, // enable click navigation
  minMarkerThickness: 2, // minimum marker height in pixels
})

Custom Marker Types

overviewRulerMarkers.of([
  { from: 100, to: 150, type: "error" },
  { from: 200, to: 250, type: "warning" },
  { from: 300, to: 350, type: "info" },
  { from: 400, to: 450, type: "search" },
  { from: 500, to: 550, type: "git-added" },
  { from: 600, to: 650, type: "todo", priority: 10 },
])

Marker Properties

| Property | Type | Description | |----------|------|-------------| | from | number | Start position in document | | to | number | End position in document | | type | string | Marker type (determines CSS class) | | className | string | Additional CSS class | | severity | "error" \| "warning" \| "info" \| "hint" | Semantic severity level | | priority | number | Higher priority markers render on top |

Theming

The ruler uses CSS custom properties for colors. Define these in your theme:

.cm-overview-ruler {
  --cm-overview-ruler-error: #ff5555;
  --cm-overview-ruler-warning: #ffaa00;
  --cm-overview-ruler-info: #00aaff;
  --cm-overview-ruler-hint: #888888;
  --cm-overview-ruler-default: #888888;
}

Built-in Marker Types

• error - Red markers (e.g., lint errors)
• warning - Orange markers (e.g., lint warnings)
• info - Blue markers (e.g., informational)
• hint - Gray markers (e.g., hints)
• default - Fallback gray markers

CSS Classes

| Class | Description | |-------|-------------| | .cm-overview-ruler | The ruler container | | .cm-overview-ruler-marker | Base marker element | | .cm-overview-ruler-{type} | Marker of specific type |

Performance

The package is designed to handle large marker sets efficiently:

• Markers are aggregated when they overlap at similar visual positions
• DOM updates are throttled using requestAnimationFrame
• Resize handling uses ResizeObserver
• Handles 100,000+ markers without significant performance degradation

Requirements

• CodeMirror 6 (@codemirror/state and @codemirror/view v6)

License

MIT © Zulfazli (Fazelllyyy)

GitHub: fazel-studio/codemirror-overview-ruler NPM: @fazelstudio/codemirror-overview-ruler