API reference

Emoji images (vector mode). null = the browser draws emoji. Default: our Noto set (DEFAULT_EMOJI_BASE_URL).

Fonts for characters a design font lacks (vector mode). false turns them off: those characters are left to the browser. Default: Google's Noto fonts, only the missing characters.

Where fonts come from: the address for a family's faces, a lookup for your own fonts, and a callback when one can't load.

Your license key, from your licenses page at mycreativeshop.com. Without one, or on a domain the license does not cover, everything still works and each text box shows a small mark: "Development" on localhost, staging and other domains not on your license, "Unlicensed" on any other site. Can be set at any time; null removes it.

How glyphs are drawn: "native" (the browser's text drawing) or "vector" (HarfBuzz outlines — identical on screen, in print and on a server). Default "vector". Fixed once the first text box exists: set it before creating any (a later change is ignored, with a console warning).

Hunspell dictionary files for spellcheck, fetched from the page. Default: the US English dictionary bundled with the library. Loaded once, when spellcheck starts.

The editor session this manager belongs to (createRichTextContext()): managers in one context share undo and editing state (an editor with several pages, one manager per page); managers in different contexts never see each other (an offscreen copy, a preview). Default: the page-wide default context.

"library" history mode only: true = the library does not act on Ctrl+Z / Ctrl+Y (Cmd on Mac) while a box is being edited; the app binds those keys and calls manager.undo() / redo().

Not needed in "host" mode: there the library keeps no list, so its keys change nothing and the app's own undo (which restores steps with context.restore) is the only one.

Show the library's right-click menu on the box being edited: spelling suggestions, Add to dictionary and Ignore (on a misspelled word), then Cut, Copy and Paste. Set to false to handle right-clicks yourself; right-clicks anywhere else are always left to your app.

Underline misspelled words while editing, with suggestions in the right-click menu. The English dictionary starts downloading in the background as soon as the manager is created.

false = render-only: boxes lay out, draw and take API calls (setText, formatting…), but nothing listens to the pointer or keyboard — no stage, window or box handlers, no edit mode. For offscreen copies, previews and print. Default true.

The layer the text lives on. Default: the stage's first layer.

Callback to intercept mousedown events on RichText nodes BEFORE the library processes them. Return true to prevent the library from handling the event (e.g., to prevent exit mode). Return false to allow normal library processing.

This is useful when you want to prevent edit mode from exiting under specific conditions, such as when clicking on custom controls or specific areas within a RichText node.

const manager = new RichTextManager({
  // ... other config
  onBeforeMouseDown: (e, richText) => {
    const pos = richText.getRelativePointerPosition();

    // Prevent exit if clicking in top-left control area
    if (pos.x < 50 && pos.y < 50) {
      console.log('Clicked control area - staying in edit mode');
      return true; // Prevent library from processing
    }

    return false; // Allow normal processing
  }
});

Callback fired when clipboard access is denied during a paste operation. This typically happens when the user blocks clipboard permission in the browser, or when pasting via context menu without granted permission.

Use this to show a user-friendly message suggesting Ctrl+V or updating permissions.

Note: This callback is NOT fired if there is content in the internal clipboard (content copied from within the editor), since that content will be pasted instead.

const manager = new RichTextManager({
  // ... other config
  onClipboardAccessDenied: () => {
    showToast("Clipboard access denied. Use Ctrl+V to paste external content.");
  }
});

A box's text or formatting changed - for autosave or an "unsaved changes" mark. Called after every change people make (typing, formatting, a resize, Story Mode) and every undo and redo, once per change: each keystroke too, so debounce a save. Changes your own code makes outside the library's commands are not reported. Every manager hears its own boxes; context.onDocumentChange hears every box of a context.

Callback fired when a user exits a text box that is empty (contains only whitespace/line breaks). The consuming application can decide how to handle this (e.g., remove the node, detach from transformer).

The node's getLastNonEmptyDocument() method can be used to retrieve the last meaningful content for undo.

const manager = new RichTextManager({
  // ... other config
  onEmptyBlur: (node) => {
    // Get last non-empty content for undo
    const lastDoc = node.getLastNonEmptyDocument();
    if (lastDoc) {
      myUndoStack.push({
        type: 'delete',
        document: lastDoc,
        x: node.x(),
        y: node.y(),
      });
    }

    // Detach from manager (cleans up internal state)
    manager.detachRichText(node);

    // Remove from transformer and layer
    const transformer = stage.findOne('#myTransformer') as Konva.Transformer;
    const currentNodes = transformer.nodes().filter(n => n !== node);
    transformer.nodes(currentNodes);
    node.destroy();
    layer.draw();
  }
});

Callback fired when a RichText node enters edit mode. Useful for showing formatting toolbars, tracking analytics, or updating UI state.

const manager = new RichTextManager({
  // ... other config
  onEnterEditMode: (node) => {
    showFormattingToolbar();
    trackActivity('richtext_edit_started');
  }
});

Callback fired when a RichText node exits edit mode. Useful for hiding formatting toolbars, saving changes, or updating UI state.

const manager = new RichTextManager({
  // ... other config
  onExitEditMode: (node) => {
    hideFormattingToolbar();
    saveChanges(node);
  }
});

Called whenever the selected text boxes change, with the boxes now selected (an empty array when none is). Other selected shapes are not included.

Callback fired when Story Mode is entered. Story Mode provides a fullscreen text editing overlay, particularly useful on mobile devices. Use this to hide UI elements, pause other interactions, etc.

const manager = new RichTextManager({
  // ... other config
  onStoryModeEnter: (node) => {
    hideFormattingToolbar();
    disableCanvasInteractions();
  }
});

Callback fired when Story Mode is exited (either saved or cancelled). Use this to restore UI state, show toolbars again, etc.

const manager = new RichTextManager({
  // ... other config
  onStoryModeExit: (node, wasSaved) => {
    enableCanvasInteractions();
    if (wasSaved) {
      trackActivity('story_mode_edit_saved');
    }
  }
});

Where a box is on screen for Story Mode's overlay (default: worked out from the stage). See StoryModeConfig.placement.

How large a box's text looks for Story Mode's attached panel (default: from the stage). See StoryModeConfig.scale.

Where the app's transformers are (selectors). selection: the one the app attaches to selected nodes — default "Transformer", i.e. any Konva.Transformer on the stage. groupChild: the one for a text box selected INSIDE a group — default: the selection transformer.

When text saved by an older version of the library moves to the latest rendering (it may shift slightly): "never" (default) — it keeps rendering exactly as it was saved, edited or not; "immediately" — as it loads. New text is always the latest. See the Upgrading guide.

Editing, formatting and text operations: toggleBold(), setText(), undo(), copy() and the rest.

Remove everything this added — listeners, the caret, its boxes' registrations. The stage stays.

The caret's width in CSS pixels (default 1.5), as Konva's.

The right-click menu while editing (default on): spelling suggestions, then Cut / Copy / Paste. See contextMenu.

Spellcheck while a box is edited (default on): misspelled words get a red squiggle, and the right-click menu (contextMenu) offers suggestions, Add to dictionary and Ignore. The dictionary (US English) downloads the first time it is needed. False: no spellcheck.

Who keeps the undo steps: "library" (default) - undo, redo and their keys work by themselves; "host" - every step goes to onHistoryStep, for your app's own undo stack beside its other changes, and restore applies one; "none" - no history (previews, print).

The object controls (default on): a click selects the box it lands on (a second click edits it), a drag moves it, and handles resize it - corners scale the type uniformly (Alt: about the center), sides change the width, never narrower than the longest word. The look is yours (handle size and colors); the behavior is the same on every surface. False: a host with its own object UI selects (select), moves and resizes itself (the resize rules are in @mycreativeshop/rich-text/kit).

Called whenever the text boxes need repainting: schedule your render (e.g. requestAnimationFrame).

A box's text or formatting changed - for autosave or an "unsaved changes" mark. Called after every change people make (typing, formatting, a resize, Story Mode) and every undo, redo and restore, once per change: each keystroke too, so debounce a save. Changes your own code makes outside the library's commands are not reported.

A box was left EMPTY when editing ended (before onExitEditMode) - e.g. remove it.

A box entered edit mode.

A box left edit mode.

"host" history: every step, as it happens - keep it in your app's undo stack.

Story Mode opened on a box (enterStoryMode).

Story Mode closed: wasSaved true for exitStoryMode or its Done button, false for cancel.

Device pixels per CSS pixel your canvas is drawn at - the scale you apply for a sharp canvas (canvas.width = css width × ratio; ctx.scale(ratio, ratio)). Default the screen's (window.devicePixelRatio). The caret and the handles are sized in CSS pixels on screen, as on Konva.

The selection highlight (default the Konva editor's, translucent blue).

Where a box is on screen, so Story Mode's overlay opens over it on desktop: your canvas element and the box's rectangle in its CSS pixels. Without it the overlay opens centered. See StoryModeConfig.placement.

How large a box's text looks on screen (your zoom), for Story Mode's attached panel. Default: 1.

When text saved by an older version of the library moves to the latest rendering (it may shift slightly): "never" (default) - it keeps rendering exactly as it was saved, edited or not; "immediately" - as it loads. New text is always the latest. See the Upgrading guide.

Alt: a resize grows about the box's center.

0 = the primary button (default). A touch is primary.

"mouse" | "pen" | "touch" (touch gets larger thresholds).

Shift held: a click extends the text selection.

The event's own timestamp (performance.now() clock).

Horizontal position, in scene coordinates.

Vertical position, in scene coordinates.

Creates a text box. It starts loading the fonts its document uses right away (without blocking) and lays the text out once they are ready. Await fontsReady() on the box, or richTextReady for a whole stage, when you need the final layout.

Returns RichText

PUBLIC API: Manually bake scale into document attributes Useful for programmatic transforms or custom transformer setups

In vector text rendering mode, checks whether this box would break its text into different lines in native mode (the browser's own text drawing).

The two modes differ only for characters the box's fonts lack, and for emoji: vector mode draws them from the library's own fallback fonts and emoji set, native mode from the device's fonts. A box without any such character cannot differ, and the method returns null at once. Otherwise it lays out a hidden copy the native way and compares the lines; this box does not change.

Returns Promise<null | NativeLayoutComparison>

null when not in vector mode or when the modes cannot differ; otherwise the lines in each mode, whether they differ, and the characters drawn from the library's fallback fonts (which can look different between the modes even when the lines match).

Copyfit a new document into this node by scaling typography to fit within fixed dimensions. The node's x, y, width, and height remain unchanged. The document is scaled to fit. Uses binary search to find the optimal scale factor.

Returns number

The final scale factor that was applied (1.0 = no scaling, 0.5 = 50% scale, etc.)

const richText = new RichText({ x: 100, y: 100, width: 300, height: 200, document: oldDoc });
const scaleFactor = richText.copyfitDocument(newLargeDoc);
console.log(`Content scaled to ${scaleFactor * 100}% to fit`);

Override destroy to clean up font loading state

Returns this

Resolves when this node's most recent async initialization (font loading

• initial layout) has finished. Useful for consumers that must rasterize the canvas only after fonts are loaded — e.g. headless PDF/image export. load() starts initialization in the background; await this to know when it's safe to capture the stage.

Never rejects — _initializeAsync handles its own errors internally (transitions to ERROR state) so awaiters get a clean settle either way.

Returns Promise<void>

How far the text bends, in degrees of arc: positive bends up, negative bends down, 180 is a half circle. Default 180. For text set on a circle of a fixed radius (DocumentCurve.arcRadius), the bend worked out from the text's width.

Returns number

Whether the text is drawn on a curve.

Returns boolean

The box's document. This is the live object the box draws, not a copy: don't change it in place. To change the text, edit a copy and pass it to setDocument.

Returns RichTextDocument

The box's current document.

Get the last non-empty document state Useful for undo operations when a text box is deleted

Returns null | RichTextDocument

The last document that contained meaningful content, or null if never had content

The box's current layout — its lines, every letter's position and metrics, its content width and text height, its longest word — as last laid out. Read-only: for hosts that measure what is on the canvas (where the ink is, which colors are drawn). Never lays out.

Returns TextLayout

The width of the widest single word in the text, in pixels, letter spacing and list indent included: the narrowest the box can be without a word overflowing it. Useful as a minimum width when resizing. Measured with the fonts loaded so far.

Returns number

The smallest font size the text is drawn at, in pixels: each run's own size, or its paragraph's where the run sets none. Useful to keep text legible, for example to stop shrinking at a minimum size.

Returns null | number

The smallest size, or null when the document has no paragraphs.

Get the current transformer instance

Returns null | Transformer

The current transformer or null if none is set

Get all unique colors used in this RichText node's document Returns both text colors and stroke colors as separate arrays All colors are deduplicated and normalized to lowercase

Returns UsedColors

Object containing arrays of unique text colors and stroke colors

Get all unique font families used in this RichText node's document

Returns string[]

Array of font family names used in the document

Lay doc out at width the way this box would — its fonts, its measurer, its fallback size — and return the result WITHOUT applying it: the box's document, size and lines are untouched. For trial layouts (copyfit's scales, an app's "does this fit?"). Measures with the fonts already loaded, as the box itself does.

Returns TextLayout & { box: { height: number; width: number } }

Replace colors in the document with new colors Supports bulk replacement operations with multiple color mappings This method modifies the document in place, triggers a redraw, and adds to history

Returns ColorReplacementResult

Result object with count of replacements made

const result = richText.replaceColors([
  { replaceColor: '#fff', newColor: '#000' },
  { replaceColor: '#333', newColor: '#999' }
]);
console.log(`Replaced ${result.replacedCount} color instances`);

Replace font families in the document and optionally re-copyfit.

Follows the same atomic history pattern as replaceColors: captures a before snapshot, mutates the document in-place, applies copyfitting when a containerHeight constraint is provided, then captures an after snapshot and pushes a single history entry.

Merge fields: fill this box's {{id}} markers (any case) with their values, each value in its marker's style (core/variables.ts, the one rule). Not an undo step. A character a value brings that the box's fonts lack is fetched as after any edit, and fontsReady waits for it. Returns whether anything was filled.

Returns boolean

Resize this RichText node for a new scale.

This method updates the node's dimensions, position, and document content to match a new page/canvas scale. Unlike setAttrs(), this properly triggers layout recalculation.

If fonts are already loaded, layout is calculated immediately (synchronous). If fonts need to be loaded, the method returns immediately and layout will be calculated automatically when fonts finish loading (triggering a redraw).

// Resize for a canvas that's 2x larger
richText.resize(2.0, 2.0);
layer.draw(); // Will show correctly even if fonts still loading

Set how far the text bends, in degrees of arc, from -360 to 360: positive bends up (the text sits on top of a circle), negative bends down. It is drawn only while the curve is on (setCurveEnabled).

A box on screen lays itself out and redraws at once. Not an undo step: from a toolbar, use the editing manager's setCurveAmount, which also turns the curve on and records one.

box.setCurveAmount(120);
box.setCurveEnabled(true);

Turn curved text on or off. Turning it on remembers the box's width; turning it off gives the box that width back. The bend is set with setCurveAmount.

Replace the box's document. When its fonts are already loaded the box is laid out and redrawn at once; otherwise the missing faces are fetched and it is laid out when they arrive. node.setAttr("document", doc) and setAttrs({ document }) come through here too.

Sets the box's width, as box.width(value) does. The text wraps to the new width.

Returns this

Whether the box handles resizing by a Konva.Transformer itself: a side handle changes the width and the text rewraps; a corner handle scales the text in proportion. Set to false to leave transforms to Konva's default scaling. Default true.

Copyfitting configuration - auto-scale content to fit fixed dimensions. When enabled, text will be scaled to fit within the node's width/height.

The text and its formatting. Build one with createDocumentFromText("..."), or pass a document you saved earlier. Default: an empty document.

Curve state — stored in node.attrs for serialization

false: a read-only box - it is selected, moved and resized like any other, but a click never starts editing and Story Mode does not open on it. Change it later with box.setAttr("editable", false). Default true.

The Konva.Transformer that resizes this box, when you do not use enableRichText (which tracks your transformer for you).

Settings for a new Konva.Transformer created for this box, used when transformer is not given. Read it back with getTransformer() and add it to a layer yourself.

Serialized attributes (the document, the curve…), as a Konva node's attrs.

Copyfit a new document into this node by scaling typography to fit within fixed dimensions. The node's x, y, width, and height remain unchanged. The document is scaled to fit. Uses binary search to find the optimal scale factor.

Returns number

The final scale factor that was applied (1.0 = no scaling, 0.5 = 50% scale, etc.)

const richText = new RichText({ x: 100, y: 100, width: 300, height: 200, document: oldDoc });
const scaleFactor = richText.copyfitDocument(newLargeDoc);
console.log(`Content scaled to ${scaleFactor * 100}% to fit`);

Resolves when this node's most recent async initialization (font loading

• initial layout) has finished. Useful for consumers that must rasterize the canvas only after fonts are loaded — e.g. headless PDF/image export. load() starts initialization in the background; await this to know when it's safe to capture the stage.

Never rejects — _initializeAsync handles its own errors internally (transitions to ERROR state) so awaiters get a clean settle either way.

Returns Promise<void>

How far the text bends, in degrees of arc: positive bends up, negative bends down, 180 is a half circle. Default 180. For text set on a circle of a fixed radius (DocumentCurve.arcRadius), the bend worked out from the text's width.

Returns number

Whether the text is drawn on a curve.

Returns boolean

The box's document. This is the live object the box draws, not a copy: don't change it in place. To change the text, edit a copy and pass it to setDocument.

Returns RichTextDocument

The box's current document.

Get the last non-empty document state Useful for undo operations when a text box is deleted

Returns null | RichTextDocument

The last document that contained meaningful content, or null if never had content

The box's current layout — its lines, every letter's position and metrics, its content width and text height, its longest word — as last laid out. Read-only: for hosts that measure what is on the canvas (where the ink is, which colors are drawn). Never lays out.

Returns TextLayout

The width of the widest single word in the text, in pixels, letter spacing and list indent included: the narrowest the box can be without a word overflowing it. Useful as a minimum width when resizing. Measured with the fonts loaded so far.

Returns number

The smallest font size the text is drawn at, in pixels: each run's own size, or its paragraph's where the run sets none. Useful to keep text legible, for example to stop shrinking at a minimum size.

Returns null | number

The smallest size, or null when the document has no paragraphs.

Get all unique colors used in this RichText node's document Returns both text colors and stroke colors as separate arrays All colors are deduplicated and normalized to lowercase

Returns UsedColors

Object containing arrays of unique text colors and stroke colors

Get all unique font families used in this RichText node's document

Returns string[]

Array of font family names used in the document

The text's height (the box sizes itself to its text - at its width as it is now).

Returns number

The box's id: the one given in CanvasBoxConfig.id, or one made up for it.

Returns string

Lay doc out at width the way this box would — its fonts, its measurer, its fallback size — and return the result WITHOUT applying it: the box's document, size and lines are untouched. For trial layouts (copyfit's scales, an app's "does this fit?"). Measures with the fonts already loaded, as the box itself does.

Returns TextLayout & { box: { height: number; width: number } }

Paint the box in its own coordinates (the caller has applied its matrix).

Replace colors in the document with new colors Supports bulk replacement operations with multiple color mappings This method modifies the document in place, triggers a redraw, and adds to history

Returns ColorReplacementResult

Result object with count of replacements made

const result = richText.replaceColors([
  { replaceColor: '#fff', newColor: '#000' },
  { replaceColor: '#333', newColor: '#999' }
]);
console.log(`Replaced ${result.replacedCount} color instances`);

Replace font families in the document and optionally re-copyfit.

Follows the same atomic history pattern as replaceColors: captures a before snapshot, mutates the document in-place, applies copyfitting when a containerHeight constraint is provided, then captures an after snapshot and pushes a single history entry.

Merge fields: fill this box's {{id}} markers (any case) with their values, each value in its marker's style (core/variables.ts, the one rule). Not an undo step. A character a value brings that the box's fonts lack is fetched as after any edit, and fontsReady waits for it. Returns whether anything was filled.

Returns boolean

The rotation in degrees, clockwise, about the box's top-left corner.

Returns number

Always 1: a canvas box is never scaled (resizing scales its type instead).

Returns number

Always 1: a canvas box is never scaled (resizing scales its type instead).

Returns number

Set how far the text bends, in degrees of arc, from -360 to 360: positive bends up (the text sits on top of a circle), negative bends down. It is drawn only while the curve is on (setCurveEnabled).

A box on screen lays itself out and redraws at once. Not an undo step: from a toolbar, use the editing manager's setCurveAmount, which also turns the curve on and records one.

box.setCurveAmount(120);
box.setCurveEnabled(true);

Turn curved text on or off. Turning it on remembers the box's width; turning it off gives the box that width back. The bend is set with setCurveAmount.

Replace the box's document. When its fonts are already loaded the box is laid out and redrawn at once; otherwise the missing faces are fetched and it is laid out when they arrive. node.setAttr("document", doc) and setAttrs({ document }) come through here too.

Moves the box and asks for a repaint. Not an undo step.

Rotates the box and asks for a repaint. Not an undo step.

A width DECIDED by someone (the text re-wraps); the box's own layout writes go through the same rule.

The width the text wraps at, in scene units.

Returns number

The left edge of the box, in scene coordinates.

Returns number

The top edge of the box, in scene coordinates.

Returns number

Shrink the type to fit a height when the box first loads (see copyfit).

The text and its formatting: createDocumentFromText("...") for plain text, or a document you saved earlier (the same format the Konva RichText uses).

Text on an arc (as a saved Konva box carries it): { enabled, amount } in degrees.

false: the box is selected and moved like any other, but never edited (attrs.editable later).

Optional id (one is made up otherwise): what undo history and events know the box by.

Degrees, clockwise, about the box's top-left corner.

The width the text wraps at. The height follows the text.

The left edge of the box, in scene coordinates.

The top edge of the box, in scene coordinates.

Fixed container height for copyfitting. When set, the algorithm uses this as the vertical constraint instead of the node's auto-calculated height. Essential when text content has been replaced before loading — without this, the auto-calculated height always matches the content and copyfit has no constraint to shrink against.

Enable copyfitting for this node

Maximum allowed font size - caps any font in the document

Minimum allowed font size - stops shrinking if any font hits this

Replacement text for copyfitting pre-modified elements. When set, the node renders its original text/document first (measuring design-intent height), then builds a new document from this text and copyfits it within that height. Each \n-delimited line becomes a paragraph block, inheriting formatting from the original document.

Works for both Konva.Text and RichText source elements — the original document structure provides all formatting; only the text changes.

How far the text bends, in degrees of arc, from -360 to 360: positive bends up (the text sits on top of a circle), negative bends down (it hangs from the bottom of one). 180 is a half circle. Ignored when arcRadius is set.

Set the text on a circle of exactly this radius, in pixels: the bend is worked out from the text's own width, and amount is ignored. For text around a round badge or sticker.

With arcRadius and centerY: the x of the circle's center, in the box's parent coordinates (the same space as the box's own x). The box is moved so its arc sits on that circle when it is first laid out; after that it can be dragged freely.

With arcRadius and centerX: the y of the circle's center, in the box's parent coordinates.

Whether the text is drawn on the curve. While the text is being edited it is drawn flat.

The box's width before the curve was turned on, in pixels. The box returns to it when the curve is turned off. Managed by the library.

With arcRadius: which side of the circle the text runs along. "top" bends up, "bottom" bends down. Default "top".

The formatting a toolbar shows: at the caret or selection while editing, else of the first letter.

Returns null | FormattingState

The current box's plain text (the first of boxes), paragraphs joined by newlines.

Returns string

The type times factor, in proportion (a headline stays a headline); setFontSize gives one size.

Set the horizontal alignment. It belongs to paragraphs: every paragraph the selection touches changes as a whole.

Change the marker of the reached list items: "disc", "circle", "square", or any single character. Paragraphs that are not list items are left as they are.

Set the text color, as any CSS color string. Also removes an image or gradient fill.

Bend the text into an arc (degrees; turns the curve on).

Replace the whole document: one undo step.

An image or gradient painted through the letters (null: back to their colors).

Change the font family, for example "Georgia". The promise resolves once the font is loaded and the text is laid out in it; until then the boxes keep their current font. Bold, italic and weight are kept. Changing several boxes is one undo step. options: a custom font's stylesheet address and details, saved in the document with the family (see FontFamilyOptions).

Returns Promise<void>

The size as getFormattingState shows it (a scaled group's text: at the group's scale). Every reached letter takes it.

A numeric weight (100–900): the source of truth over bold.

Set the extra space between letters, in pixels as seen; 0 is the font's normal spacing. Applies to whole paragraphs.

Set the line height, as a multiple of the font size (1.2 is 120%). Applies to whole paragraphs.

Space after each paragraph (multiples of its font size).

Set the drop shadow, or remove it with null. The shadow belongs to the whole box, never to a selection. It changes only how the text is painted, never its layout.

Set the outline color, as any CSS color string. Visible only where the outline width is above zero.

Set the width of the letters' outline, in pixels as seen. 0 removes it. If none of the reached letters has an outline color yet, black is used.

Set the tab stops of whole paragraphs: where the text after each tab sits ({ pos: 1, align: "right", leader: "dots" } parks a price at the right edge behind dots). [] removes them; a tab then goes to the next default stop.

Replace the text, keeping the formatting of the first letter and paragraph.

Turn bold on or off, following what the toolbar shows: if FormattingState.bold is true it is removed, otherwise applied. Also sets the numeric weight to 700 or 400.

Make the reached paragraphs bulleted list items, or plain paragraphs again: if any is not a list item yet, all become list items; otherwise all lose their bullets.

Curve the box's text along an arc, or straighten it again. Applies to the whole box. Experimental.

Turn italic on or off, following what FormattingState.italic shows.

Turn strikethrough on or off, following what FormattingState.strikethrough shows.

Turn underline on or off, following what FormattingState.underline shows.

The editor session this manager belongs to (see RichTextManagerConfig.context).

The text boxes this manager edits (every RichText on its stage).

Returns RichText[]

Cancel Story Mode without saving changes. Call this from your dialog's Cancel button.

Copy selected text to clipboard. This method can be called from consuming applications that want to implement custom copy functionality (e.g., custom context menus, toolbar buttons).

Returns boolean

true if text was copied, false if no selection or not in edit mode

// In a custom context menu handler
menuButton.addEventListener('click', () => {
  manager.copy();
});

Cut selected text to clipboard. This method can be called from consuming applications that want to implement custom cut functionality (e.g., custom context menus, toolbar buttons).

Returns boolean

true if text was cut, false if no selection or not in edit mode

// In a custom context menu handler
menuButton.addEventListener('click', () => {
  manager.cut();
});

Stop managing everything: leaves editing, and removes exactly what this manager added — its stage and box handlers (namespaced ".richtextManager"; the host's own handlers stay), its window keyboard/paste listeners, and its boxes from the context's map and editing state. After this, nothing reacts to keys or clicks on its behalf.

Start editing richText now, as a tap on it while selected would: it becomes the selection and takes the caret. For a host gesture that should go straight to typing (a double-click on a decorated group whose words are the point). A box marked editable: false declines, exactly as it declines a tap.

The text box being edited, or null.

Returns null | RichText

Opens Story Mode - a larger editor for long text, over the canvas - on box, else on the box being edited, else on the selected box. Inside your own panel after setStoryModeContainer. While it is open, formatting commands reach the text selected in the panel. A box marked editable: false doesn't open.

Exit Story Mode and save changes. Call this from your dialog's Apply/Save button.

Returns null | RichText

The updated RichText node, or null if validation failed

Check if there is currently a text selection. Useful for determining whether copy/cut operations are available.

Returns boolean

true if there is a selection, false otherwise

Check if Story Mode is currently active

Returns boolean

Paste content from clipboard into the currently editing RichText node. This method should be called from consuming applications that want to implement custom paste functionality (e.g., custom context menus, toolbar buttons).

Note: This method must be called during a user gesture (e.g., button click) to have clipboard access. If called outside a user gesture context, clipboard access may be denied by the browser.

Returns Promise<void>

Promise that resolves when paste is complete

// In a custom context menu handler
menuButton.addEventListener('click', async () => {
  await manager.paste();
});

Redo the last undone operation

Merge fields: fill {{id}} markers (any case) with their values, each value in its marker's style - in every box this manager edits, or only boxes (one name on every surface: a box's own replaceVariables, the canvas's rt.replaceVariables). Not an undo step.

The selected text box on this stage, or null (TextFormatting's "current box" when none is being edited).

Returns null | RichText

Set the container for Story Mode. Call this before enterStoryMode() with your dialog's content div.

// User clicks button to open dialog
const dialog = createMyDialog();
const editorDiv = dialog.querySelector('#story-editor-container');

manager.setStoryModeContainer(editorDiv);
manager.enterStoryMode();

Stop editing (the caret and selection go; the box stays selected).

Undo the last operation

Add a text box to the scene.

Returns CanvasTextBox

The boxes, bottom to top (the order paint draws them in).

Returns readonly CanvasTextBox[]

Closes Story Mode and puts the box's text back as it was.

The click the browser sends after a press and release on the same spot.

Returns { handled: boolean }

The browser's contextmenu event (a right-click): on the box being edited, the library's menu opens at screen (the event's clientX / clientY) - spelling suggestions for a misspelled word, then Cut / Copy / Paste. handled: it opened (call preventDefault() on the event so the browser's own menu doesn't).

Returns { handled: boolean }

Copy the selected text to the clipboard. Returns whether there was a selection.

Returns boolean

The mouse cursor at the last pointer event (a CSS cursor name) - the same rule on every surface. Apply it after each pointer call: canvas.style.cursor = rt.cursor().

Returns string

Cut the selected text to the clipboard (an undo step). Returns whether there was a selection.

Returns boolean

Stop listening and release every box.

The box being edited, or null.

Returns null | CanvasTextBox

Opens Story Mode - a larger editor for long text, over the canvas - on box, else on the box being edited, else on the selected box. The overlay opens over it when storyModePlacement says where it is, centered otherwise; or inside your own panel after setStoryModeContainer. While it is open, formatting commands reach the text selected in the panel. A box marked editable: false doesn't open.

Closes Story Mode and writes its text to the box (one undo step). Returns the box, or null.

Returns null | CanvasTextBox

A DOM pointer event as a CanvasPointer: canvas pixels, then (optional) the host's scene matrix inverted.

Returns CanvasPointer

Is text selected in the box being edited? (Whether copy and cut can do anything.)

Returns boolean

The topmost box under a scene point, or null.

Returns null | CanvasTextBox

Whether Story Mode is open.

Returns boolean

The formatting at the caret (while editing) or of the selected box, whenever it changes: a toolbar follows it. Called at once with the current state. Returns the unsubscribe.

Returns () => void

Paint every box, each under its own matrix, on top of the context's current transform.

Paint the caret and the selection of the box being edited (call after everything else).

Paste the clipboard at the caret (call from a user gesture). Resolves false when no box is being edited.

Returns Promise<boolean>

Pointer input. handled: the text editor took the event (else it is the host's).

Returns { handled: boolean }

Pointer movement: drag-selecting text, moving or resizing a box with the object controls, and hover feedback. handled: the library used the event (else it is the host's).

Returns { handled: boolean }

Pointer release: ends a drag-select, move or resize. handled: the library used the event.

Returns { handled: boolean }

Every box on its real fonts and laid out - what to await before exporting or measuring (Konva: richTextReady). Bounded by the font time limit, so a font that never arrives can't hold it forever.

Returns Promise<void>

Redoes the last undone change. While a box is being edited, Ctrl+Y (Cmd+Y on Mac) does the same.

Take a box out of the scene.

Merge fields: fill {{id}} markers (any case) with their values, each value in its marker's style - in every box, or only boxes. Not an undo step. (One name on every surface: a box's own, Konva's manager.replaceVariables.)

"host" history: undo ("before") or redo ("after") a step your app kept from onHistoryStep - every box it covers goes back to that state, as the library's own undo would put it. Returns how many boxes were restored.

Returns number

Select a box (or none). A selected box's next click edits it.

The selected box, or null.

Returns null | CanvasTextBox

Render Story Mode inside your own element (a panel or dialog) instead of an overlay; undefined: the overlay.

Leave edit mode.

Undoes the last text change (typing, formatting, a move or resize). The boxes it changes are restored and selected; edit mode stays as it was. While a box is being edited, Ctrl+Z (Cmd+Z on Mac) does the same.

The paragraph's alignment.

The text is bold.

Redo can step forward.

Undo can step back.

The color, as CSS.

The caret's position, as a letter index in the box.

The font family.

The size in pixels, as it looks on screen (a scaled group's scale applied).

Numeric font weight of the selection (100–900), when uniform. Optional and READ-ONLY reporting — it reflects the document's existing fontWeight/bold attributes for the toolbar's weight picker; it does not affect rendering. Undefined when not resolvable (e.g. mixed weights across the selection).

Text is selected (not just a caret).

The paragraph is a list item.

The text is italic.

The paragraph's letter spacing in pixels, as it looks on screen.

The paragraph's line height, as a multiple of the font size.

The list's marker.

The list's kind, when it is a bulleted list.

The space after the paragraph, as a multiple of its font size.

How many letters are selected.

The text is struck through.

The outline's color.

The outline's width in pixels, as it looks on screen (0: none).

The paragraph's tab stops; empty when it has none (a tab then goes to the next default stop).

The text is underlined.

The font's author or license credit. Stored only.

A short, user-friendly description of the font. Stored only.

The address of a stylesheet with the font's @font-face rules. Used to load the font, and saved so the design opens anywhere.

The address of a preview image of the font, for a font picker. Stored only; never drawn.

The size, in pixels, of new text with no size of its own (an empty box's caret, a new paragraph).

The paragraphs, in order.

A gradient or image that fills every letter in the box, in place of the text colors. Setting a solid color (setColor) removes it.

Where the document's custom fonts live, recorded as fonts are applied, so the design opens anywhere without your font lookup.

The text version this document renders with (core/rendering.ts). None = version 1: made before versions existed. Saved with the text, so it renders the same wherever it goes.

A drop shadow behind all of the box's text. No shadow when absent.

The paragraph's look and layout.

The paragraph's text, in runs of one style each. A paragraph always has at least one run (an empty one: text: "").

A unique id within the document.

"paragraph", or "list-item" for a line with a bullet or number.

How the paragraph's lines sit in the box.

Display the paragraph in capitals. The words stay as typed — only layout and paint see capitals (see displayText), so copy, paste, spellcheck and switching it off all get the real text back. Set it for headings, labels and other text shown in capitals.

A color filled behind the paragraph's lines.

The color of a border around the paragraph.

The width of that border, in pixels.

For a list item: how far its marker sits from the left, as a multiple of its font size (default 0.6).

The color of the paragraph's letters, as CSS: "#5e2dc1", "rgb(94, 45, 193)".

The font family of the paragraph's letters, e.g. "Lora" (a run may set its own).

The size of the paragraph's letters in pixels (a run may set its own).

A numeric weight for the paragraph's letters, 100-900 (a run may set its own).

Extra space after every letter, in pixels (0 is none; negative tightens).

The height of a line as a multiple of the font size: 1.2 is normal.

For a list item: how far its text sits from the left, as a multiple of its font size (default 2).

For a list item: the marker - "disc", "circle", "square", "decimal", or any character, e.g. "➤".

For a list item: "bullet" (the default) or "number".

Vector list marker, drawn instead of the listStyle character.

A marker is TWO shapes in TWO colors — a white check inside a filled circle, a digit on a rounded square — so a single path plus a single color cannot express the common cases. Omit it and the character path is used, unchanged.

Space after the paragraph, as a multiple of its font size (0 is none).

Tab stops for this block. A \t in the text advances to the next stop.

An ARRAY from the outset even though v1 ships a single right stop: a user-pressed Tab key is a stated direction, and Item ⇥ Qty ⇥ Price is the obvious first thing someone does with it. Widening this later would be a document migration; starting wide costs nothing.

The run's own style, over its paragraph's.

The run starts on a new line within its paragraph (a soft break, Shift+Enter).

The run's letters.

How many soft breaks follow the run's text (empty lines within the paragraph).

Bold (weight 700, unless fontWeight says otherwise).

The run's color, as CSS, over its paragraph's.

The run's font family, over its paragraph's.

The run's size in pixels, over its paragraph's.

A numeric weight, 100-900. Wins over bold.

Italic.

Struck through.

The color of an outline around the letters.

The width of that outline, in pixels (0 or absent: none).

Underlined.

Glyph color. Defaults to the text color, matching the character-bullet behavior.

SVG path data for the glyph, in a 24x24 viewBox. Omit for a shape-only marker.

Marker box as a multiple of fontSize. Default 1.0.

Backing shape painted behind the glyph. Omit or "none" for a bare glyph.

Fill for the backing shape. Ignored when there is no shape.

How the run after the tab sits against the stop.

v1 IMPLEMENTS "right" only; "left" and "center" are accepted and fall back to it, so a document authored by a later version stays readable by this renderer instead of throwing. Declared as a union rather than a boolean because widening a union is free and changing a boolean's shape is a migration.

Optional leader painted across the gap.

Position as a fraction of the node width. 1.0 is the right edge.

The gradient's direction in degrees, as in CSS linear-gradient: 0 runs from color1 at the bottom to color2 at the top, 90 from left to right, 180 from top to bottom.

The color the gradient starts with, any CSS color.

The color the gradient ends with, any CSS color.

Always "gradient".

How the image maps onto the text box. Defaults to "cover".

Always "image".

The image's URL. It must be loadable by the page (served with CORS when it is on another origin).

Blur radius in pixels, as in CSS text-shadow. 0 is a hard-edged shadow.

Shadow color, any CSS color. Use rgba() to make it translucent, e.g. "rgba(0, 0, 0, 0.4)".

Horizontal offset in pixels; positive moves the shadow right.

Vertical offset in pixels; positive moves the shadow down.

The font's author or license notice. Informational.

A description for people choosing a font. Informational.

The font family name, exactly as the document's fontFamily attributes spell it.

A custom font's files, one per face (weight and style). Used instead of fontFaceUrl when both are given.

A custom font's stylesheet: the URL of a CSS file with @font-face rules for the family.

A preview image of the font, for font pickers. Not used to draw text.

Any other data you want saved with the font. The library does not read it.

Where the font comes from: "google" (Google Fonts), "custom" (your own files or stylesheet, given here) or "system" (installed on the device).

The faces the family offers, for font pickers, e.g. ["400", "700", "400italic"]. Informational.

The weights a custom font ships, e.g. [400, 700]. Recorded with a stylesheet font so the design draws the same weights where it opens without your fonts lookup (a weight it lacks resolves to one it has, never a fake bold). Files carry their own weights. Version 2 text reads it.

The face's style.

A .woff2, .woff, .ttf or .otf file.

The face's weight, 100 to 900 (400 is regular, 700 bold).

The field's name, as written between the braces (e.g. "phone" for {{phone}}).

The text it becomes. Written as is (a "$" is a dollar sign, never a replacement pattern). None (null): empty text.

The drop shadow's color (its opacity kept: "rgba(0, 0, 0, 0.4)").

The outline (stroke) colors drawn, each once; a stroke color with no stroke width is not drawn and not listed.

The letters' colors, each once: run and paragraph colors (or a gradient fill's two colors, which paint over them) and list marker colors. Opaque colors are given as "#rrggbb", translucent ones as "rgba(r, g, b, a)".

The color to use instead, any CSS color. Each place keeps its own opacity.

The color to replace, in any CSS spelling ("#FFF", "white" and "rgb(255, 255, 255)" all match the same color). It matches that color at any opacity.

How many places changed color in all: the sum of the three counts below.

Each replacement that changed something, with the color it matched (oldColor, as "#rrggbb"), the color it put there and how many places it changed. Replacements that matched nothing are left out.

How many shadow colors changed (0 or 1: a document has at most one shadow).

How many outline (stroke) colors changed.

How many letter colors changed (runs, paragraphs, gradient colors and list markers).

True when every family can be drawn. A family still loading when the wait ends is in neither list, and makes this false.

The error that stopped loading, when one did. Usually absent: a failed family is listed in failed.

The families that cannot be drawn: none of the faces asked for loaded. Text in them uses a stand-in font.

The families that can be drawn: at least one of the faces asked for loaded.

The family's font files, one per face. The weights it ships are these files' weights (a weight it lacks is drawn from the nearest file, never synthesized). Takes precedence over fontFaceUrl.

A stylesheet with the family's @font-face rules (a brand or uploaded font).

The weights the family ships, so a weight it lacks resolves to one it has (no fake bold).

The file itself: an upload, a font bundled with the app, offline use. Not recorded in designs.

Default "normal".

Where the file is (it must allow cross-origin requests when on another origin).

The weight this file draws, 100-900. Default 400.

The family asked for.

The style asked for.

The weight asked for, 100-900.

The family that could not be loaded.

Why. Every reason but the last is about getting the file; font-draw-failed: the file loaded, but the browser would not draw it.

The face's style.

Worth trying again later (the library does, by itself).

The address that failed, when there is one.

The face's weight.

The characters needed: a stylesheet may serve only these (a subset).

The fallback family, e.g. "Noto Sans JP".

The family has an italic axis (ask for italic in the address).

Whether the family is served with a weight / italic axis (Google's css2 needs to know).

Whether that text is italic.

The weight to match the text it stands in for.

Folder serving emoji_u.svg for the pinned release (no trailing slash).

How to turn an SVG file into something drawImage takes. Defaults to the browser's.

The widest line (a box this wide shows every line unwrapped by it).

Every grapheme's position and metrics, as a box's layout produces them.

The height the text needs (a box sizes itself to this).

The lines, as a box's getLines() reports them.

The widest single word (for a list, plus its indent): narrower than this, a word overflows.

Baseline, in the node's own coordinates. One per line, whatever sizes the line mixes.

No visible characters — an empty paragraph kept for spacing.

The block (paragraph) this line belongs to. A wrapped paragraph spans several lines.

Why the line ended: the text ran out of room (wrap), the paragraph ended (paragraph), an authored in-paragraph break (softbreak), or it is the last line (end).

The line's words, joined as laid out, without the whitespace a wrap swallowed.

Visible extent, list indent and tab columns included — what maxLineWidth is the max of.

The baseline of the letter's line, in pixels. Every letter on a line shares it.

The id of the paragraph (block) the letter is in.

The letter's color, as the document gives it.

The font family the letter is drawn in.

The font size the letter is drawn at, in pixels.

The letter as drawn (one user-perceived character, which may be several code points, such as an emoji).

The letter's height, in pixels: its ascent plus its descent.

The letter's advance width, in pixels, letter spacing not included.

The letter's left edge, in pixels. Includes the line's alignment and any list indent.

The top of the letter's box, in pixels: its baseline minus its ascent.

The characters drawn from the library's fallback fonts (and emoji set) instead of the device's. These can look different between the modes even when linesChanged is false.

True when the two modes break the text into different lines.

The text of each line as native mode would set it, top to bottom.

The text of each line as the box sets it now (vector mode), top to bottom.

A box's text or formatting changed: every change people make (typing, formatting, a resize, Story Mode), and every undo, redo and restore. Called after the change is applied, once per change - each keystroke too, so debounce an autosave. Changes your own code makes outside the library's commands (replaceVariables, setDocument on the box itself) are not reported: your code made them. Returns a function that unsubscribes.

Returns () => void

Formatting reports for this session's boxes: called with the formatting at the caret / selection (bold, size, color…) and the box, whenever it changes — to keep a toolbar in step. It is also called once right away with the latest report (null formatting when there is none). Returns a function that unsubscribes.

Returns () => void

"host" history mode: undo ("before") or redo ("after") a step the app kept — every box it covers goes back to that snapshot, exactly as the library's own undo would put it (document, size, position, scale, curve, caret). Boxes no manager of this context has any more (deleted) are skipped; returns how many were restored.

Returns number

Each box the step changed, with its state before and after.

The step's group number. Consecutive steps with the same number are one step to the user: merge them by keeping the first step's before states and the latest step's after states.

What kind of change it was: "typing", "deletion", "formatting", or "structural" (a new paragraph, a paste, a whole-document replacement, a resize, Story Mode closing).

The box's state after the change: what redo restores.

The box's state before the change: what undo restores.

The id of the text box that changed.

Where the caret was, as a character index.

The box's document at that moment.

The box's curve settings, when it has any.

The box's height, in the box's own units (before its scale).

The box's horizontal scale.

The box's vertical scale.

Where the selection ended, as a character index, or null when nothing was selected.

Where the selection started, as a character index, or null when nothing was selected.

The box's width, in the box's own units (before its scale).

The box's x position.

The box's y position.