Skip to main 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
      );
    }
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us