Overlays and Virtual Text API

Overlay Operations

addOverlay

Add a visual overlay to a buffer range. Overlays persist until explicitly removed. Use namespaces for batch removal (e.g., "spell", "todo"). Multiple overlays can apply to the same range; colors blend.

addOverlay(buffer_id: number, namespace: string, start: number, end: number, r: number, g: number, b: number, bg_r: number, bg_g: number, bg_b: number, underline: boolean, bold: boolean, italic: boolean, extend_to_line_end: boolean): boolean

Parameters:

Name	Type	Description
buffer_id	number	Target buffer ID
namespace	string	Optional namespace for grouping (use clearNamespace for batch removal)
start	number	Start byte offset
end	number	End byte offset
r	number	Red (0-255)
g	number	Green (0-255)
b	number	Blue (0-255)
bg_r	number	-
bg_g	number	-
bg_b	number	-
underline	boolean	Add underline decoration
bold	boolean	Use bold text
italic	boolean	Use italic text
extend_to_line_end	boolean	Extend background to end of visual line

removeOverlay

Remove a specific overlay by its handle

removeOverlay(buffer_id: number, handle: string): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
handle	string	The overlay handle to remove

clearOverlaysInRange

Clear all overlays that overlap with a byte range

clearOverlaysInRange(buffer_id: number, start: number, end: number): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
start	number	Start byte position (inclusive)
end	number	End byte position (exclusive)

clearAllOverlays

Remove all overlays from a buffer

clearAllOverlays(buffer_id: number): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID

addVirtualText

Add virtual text (inline decoration) at a position

addVirtualText(buffer_id: number, virtual_text_id: string, position: number, text: string, r: number, g: number, b: number, before: boolean, use_bg: boolean): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
virtual_text_id	string	Unique identifier for this virtual text
position	number	Byte position to insert at
text	string	The virtual text to display
r	number	Red color component (0-255)
g	number	Green color component (0-255)
b	number	Blue color component (0-255)
before	boolean	Whether to insert before (true) or after (false) the position
use_bg	boolean	Whether to use the color as background (true) or foreground (false)

removeVirtualText

Remove virtual text by ID

removeVirtualText(buffer_id: number, virtual_text_id: string): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
virtual_text_id	string	The virtual text ID to remove

removeVirtualTextsByPrefix

Remove all virtual texts with IDs starting with a prefix

removeVirtualTextsByPrefix(buffer_id: number, prefix: string): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
prefix	string	The prefix to match virtual text IDs against

clearVirtualTexts

Remove all virtual texts from a buffer

clearVirtualTexts(buffer_id: number): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID

clearVirtualTextNamespace

Clear all virtual texts in a namespace

clearVirtualTextNamespace(buffer_id: number, namespace: string): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID
namespace	string	The namespace to clear (e.g., "git-blame")

refreshLines

Force a refresh of line display for a buffer

refreshLines(buffer_id: number): boolean

Parameters:

Name	Type	Description
buffer_id	number	The buffer ID

Scrollbar Markers

Paint colored marks on a split's vertical scrollbar at positions proportional to their location in the buffer — an "overview ruler". Use it alongside a line highlight (addOverlay with extendToLineEnd) and a gutter mark (setLineIndicator) so marked content is findable even when scrolled off screen.

Markers are anchored by byte offset inside the editor, so they shift with edits and stay correct between refreshes. They work identically on a ten-line file and a multi-gigabyte one: on files too large for line numbers to be known, marks are positioned by byte ratio instead.

setScrollbarMarkers

Replace a namespace's entire marker set for a buffer. The swap is atomic, so a refresh never shows a partially rebuilt set.

setScrollbarMarkers(bufferId: number, namespace: string, markers: ScrollbarMarker[]): boolean

A ScrollbarMarker is positioned by position (byte offset — preferred, and exact at any file size) or line (0-based, converted to a byte anchor when set). An optional end byte makes it a range marker that paints a proportional streak instead of a single cell. color takes an RGB triple or a theme key, resolved at render time so marks follow theme changes. priority breaks ties when several markers land on the same track cell.

editor.setScrollbarMarkers(bufferId, "my-plugin", [
  { position: 4096, color: "diagnostic.error" },
  { position: 8192, end: 9000, color: [80, 200, 120], priority: 2 },
]);

setScrollbarMarkersInRange

Replace only the markers currently anchored in [start, end), leaving this namespace's markers elsewhere in the buffer untouched.

setScrollbarMarkersInRange(
  bufferId: number, namespace: string,
  start: number, end: number,
  markers: ScrollbarMarker[],
): boolean

This is the form to use from a lines_changed handler. That hook reports only the lines the editor decided to process — usually the viewport — so a whole-namespace replace would delete the marks for everything off screen. Range scoping publishes just the region you scanned, and coverage accumulates as the user explores the document. See markdown_compose.ts, which marks headings this way.

clearScrollbarMarkers

Remove all of a namespace's markers. Namespaces are also cleared automatically when the plugin unloads.

clearScrollbarMarkers(bufferId: number, namespace: string): boolean