Overlays API

Add visual decorations to buffer text without modifying content

The Overlays API allows you to add visual decorations to buffer text - such as syntax highlighting, error markers, search results, and more - without modifying the actual buffer content.

Overlay Operations

addOverlay

Add a visual overlay to a buffer range.

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

buffer_id · number · required

Target buffer ID

namespace · string · required

Namespace for grouping (use for batch removal)

start · number · required

Start byte offset

end · number · required

End byte offset

r · number · required

Foreground red (0-255)

g · number · required

Foreground green (0-255)

b · number · required

Foreground blue (0-255)

bg_r · number · required

Background red (0-255, or -1 for transparent)

bg_g · number · required

Background green (0-255, or -1 for transparent)

bg_b · number · required

Background blue (0-255, or -1 for transparent)

underline · boolean · required

Add underline decoration

bold · boolean · required

Use bold text

italic · boolean · required

Use italic text

extend_to_line_end · boolean · required

Extend background to end of visual line

returns · boolean

true if overlay was added successfully

Overlays persist until explicitly removed. Use namespaces for batch removal (e.g., “spell”, “todo”). Multiple overlays can apply to the same range; colors blend.

Example:

// Highlight TODO comments in orange
const bufferId = editor.getActiveBufferId();
const text = await editor.getBufferText(bufferId, 0, 1000);
const match = text.match(/TODO:/i);

if (match) {
  editor.addOverlay(
    bufferId,
    "todo-highlight",  // namespace
    match.index!,       // start
    match.index! + match[0].length,  // end
    255, 165, 0,       // orange foreground
    -1, -1, -1,        // transparent background
    false,             // no underline
    true,              // bold
    false,             // not italic
    false              // don't extend to line end
  );
}

removeOverlay

Remove a specific overlay by its handle.

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

buffer_id · number · required

The buffer ID

handle · string · required

The overlay handle to remove

returns · boolean

true if overlay was removed

clearNamespace

Clear all overlays in a namespace.

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

buffer_id · number · required

The buffer ID

namespace · string · required

The namespace to clear

returns · boolean

true if namespace was cleared

Example:

// Clear all TODO highlights
editor.clearNamespace(bufferId, "todo-highlight");

clearOverlaysInRange

Clear all overlays that overlap with a byte range.

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

buffer_id · number · required

The buffer ID

start · number · required

Start byte position (inclusive)

end · number · required

End byte position (exclusive)

returns · boolean

true if overlays were cleared

clearAllOverlays

Remove all overlays from a buffer.

clearAllOverlays(buffer_id: number): boolean

buffer_id · number · required

The buffer ID

returns · boolean

true if all overlays were cleared

Virtual Text

Virtual text appears inline in the buffer without modifying the actual content. Useful for displaying inline hints, diagnostics, or git blame information.

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

buffer_id · number · required

The buffer ID

virtual_text_id · string · required

Unique identifier for this virtual text

position · number · required

Byte position to insert at

text · string · required

The virtual text to display

r · number · required

Red color component (0-255)

g · number · required

Green color component (0-255)

b · number · required

Blue color component (0-255)

before · boolean · required

Whether to insert before (true) or after (false) the position

use_bg · boolean · required

Whether to use the color as background (true) or foreground (false)

returns · boolean

true if virtual text was added

Example:

// Add inline type hint
const bufferId = editor.getActiveBufferId();
const position = editor.getCursorPosition();

editor.addVirtualText(
  bufferId,
  "type-hint-1",
  position,
  " : string",
  128, 128, 128,  // gray color
  false,          // insert after
  false           // use as foreground
);

removeVirtualText

Remove virtual text by ID.

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

buffer_id · number · required

The buffer ID

virtual_text_id · string · required

The virtual text ID to remove

returns · boolean

true if virtual text was removed

removeVirtualTextsByPrefix

Remove all virtual texts with IDs starting with a prefix.

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

buffer_id · number · required

The buffer ID

prefix · string · required

The prefix to match virtual text IDs against

returns · boolean

true if virtual texts were removed

Example:

// Remove all type hints
editor.removeVirtualTextsByPrefix(bufferId, "type-hint-");

clearVirtualTexts

Remove all virtual texts from a buffer.

clearVirtualTexts(buffer_id: number): boolean

buffer_id · number · required

The buffer ID

returns · boolean

true if all virtual texts were cleared

clearVirtualTextNamespace

Clear all virtual texts in a namespace.

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

buffer_id · number · required

The buffer ID

namespace · string · required

The namespace to clear (e.g., “git-blame”)

returns · boolean

true if namespace was cleared

Line Decorations

addVirtualLine

Add a virtual line above or below a source line.

addVirtualLine(
  buffer_id: number,
  position: number,
  text: string,
  fg_r: number,
  fg_g: number,
  fg_b: number,
  bg_r: number,
  bg_g: number,
  bg_b: number,
  above: boolean,
  namespace: string,
  priority: number
): boolean

buffer_id · number · required

The buffer ID

position · number · required

Byte position to anchor the virtual line to

text · string · required

The text content of the virtual line

fg_r · number · required

Foreground red color component (0-255)

fg_g · number · required

Foreground green color component (0-255)

fg_b · number · required

Foreground blue color component (0-255)

bg_r · number · required

Background red color component (0-255), -1 for transparent

bg_g · number · required

Background green color component (0-255), -1 for transparent

bg_b · number · required

Background blue color component (0-255), -1 for transparent

above · boolean · required

Whether to insert above (true) or below (false) the line

namespace · string · required

Namespace for bulk removal (e.g., “git-blame”)

priority · number · required

Priority for ordering multiple lines at same position

returns · boolean

true if virtual line was added

setLineIndicator

Set a line indicator in the gutter’s indicator column.

setLineIndicator(
  buffer_id: number,
  line: number,
  namespace: string,
  symbol: string,
  r: number,
  g: number,
  b: number,
  priority: number
): boolean

buffer_id · number · required

The buffer ID

line · number · required

Line number (0-indexed)

namespace · string · required

Namespace for grouping (e.g., “git-gutter”, “breakpoints”)

symbol · string · required

Symbol to display (e.g., ”│”, ”●”, ”★”)

r · number · required

Red color component (0-255)

g · number · required

Green color component (0-255)

b · number · required

Blue color component (0-255)

priority · number · required

Priority for display when multiple indicators exist (higher wins)

returns · boolean

true if line indicator was set

Example:

// Add git gutter indicator for modified line
editor.setLineIndicator(
  bufferId,
  42,                 // line number
  "git-gutter",       // namespace
  "│",                // symbol
  255, 200, 0,        // orange color
  100                 // priority
);

clearLineIndicators

Clear all line indicators for a specific namespace.

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

buffer_id · number · required

The buffer ID

namespace · string · required

Namespace to clear (e.g., “git-gutter”)

returns · boolean

true if line indicators were cleared

Examples

Highlight search results

function highlightSearchResults(bufferId: number, query: string) {
  // Clear existing highlights
  editor.clearNamespace(bufferId, "search");
  
  // Get buffer content
  const length = editor.getBufferLength(bufferId);
  const text = await editor.getBufferText(bufferId, 0, length);
  
  // Find all matches
  const regex = new RegExp(query, "gi");
  let match;
  
  while ((match = regex.exec(text)) !== null) {
    editor.addOverlay(
      bufferId,
      "search",
      match.index,
      match.index + match[0].length,
      0, 0, 0,           // black text
      255, 255, 0,       // yellow background
      false, false, false, false
    );
  }
}

Show inline diagnostics

function showDiagnostics(bufferId: number) {
  const diagnostics = editor.getAllDiagnostics();
  const path = editor.getBufferPath(bufferId);
  
  for (const diag of diagnostics) {
    if (diag.uri.endsWith(path)) {
      const message = ` ← ${diag.message}`;
      const position = /* calculate byte position from diag.range */;
      
      editor.addVirtualText(
        bufferId,
        `diag-${position}`,
        position,
        message,
        255, 0, 0,  // red for errors
        false,      // after position
        false       // foreground color
      );
    }
  }
}