Decorations API

The Decorations API allows scripts to create and manage decorations in the document editor. Decorations are visual elements that can be added to the text, such as highlights, underlines, or custom UI components. Decorations require the “editorDecorations” permission to be created.

Overview

The Decorations API is accessed via api.v1.decorations. It provides methods to create, update, and remove decorations in the document. There are three main types of decorations:

  • Rules: Apply visual styles to specific text ranges or paragraphs based on a regular expression.
  • Markers: Apply visual styles to specific text ranges or paragraphs based on positions in the document.
  • Widgets: Custom UI components that can be embedded in the document at specific positions.

Rules

Rules allow you to define visual styles that are applied to text matching a regular expression. You can specify the style, the regex pattern, and options such as case sensitivity. Example:

api.v1.editor.decorations.registerRules([{
  id: "alice-highlight",
  type: "inline",
  match: /\bAlice\b/,
  style: { backgroundColor: "rgba(255, 255, 0, 0.3)" }
}]);

This example highlights all occurrences of the word “Alice” with a yellow background.

Markers

Markers allow you to apply styles to specific text ranges or paragraphs based on their positions in the document. Example:

const pos = await api.v1.editor.selection.get();
if (pos.from === null) {
  return "No selection!";
}
const fromSection = pos.from.sectionId;
await api.v1.editor.decorations.createMarker({
  type: "node",
  sectionId: fromSection,
  style: { borderLeft: "4px solid #66ccff", paddingLeft: "4px" }
});

This example adds a blue border to the left of the selected paragraph where the cursor is located.

Widgets

Widgets allow you to embed custom UI components in the document at specific positions within a paragraph or between paragraphs. Example:

const sections = await api.v1.document.scan();
if (!sections.length) {
  return "Document is empty!";
}
const lastSection = sections[sections.length - 1];
await api.v1.editor.decorations.createWidgets([{
  type: "node",
  sectionId: lastSection.sectionId,
  side: "after",
  content: [{
    type: "box",
    style: { width: '100%' },
    content: [
      { type: "text", markdown: true, text: "🎉 **Congrats!** This widget was added by a script." },
      { type: "button", text: "Click Me", callback: () => api.v1.ui.toast("Widget button clicked!", { type: "success" }) }
    ]
  }]
}]);

This example adds a widget below the last paragraph of the document with a congratulatory message and a button.

Managing Decorations

Rules can be updated or removed using their IDs. Markers and widgets return a handle when created, which can be used to update or dispose of them. Additionally, markers and widgets accept an optional onChange callback as part of their options, which is called whenever the decoration’s position changes due to document edits or the decoration is disposed of due to collapsing or deletion.

See Also