@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