DocAuthEditor

DocAuthEditor:

{
  setCurrentDocument(doc: DocAuthDocument): void;
  currentDocument(): DocAuthDocument;
  destroy(): void;
  docAuthSystem(): DocAuthSystem;
  hasActiveCursor(): boolean;
  insertTextAtCursor(text: string): void;
  insertContentAtCursor(options: InsertContentAtCursorOptions): void;
  getSelectionContent(options: { format: F }): SelectionContentByFormat[F] | null;
  setActions(actions: Action[]): void;
  setToolbarConfig(config: ToolbarConfig): void;
  setEditorMode(mode: DocAuthEditorMode): void;
  getEditorMode(): DocAuthEditorMode;
  setAuthor(name: string): void;
  getAuthor(): string;
  enableSpellcheck(language: SpellcheckLanguage): void;
  disableSpellcheck(): void;
  on(event: EventName, handler: (payload: EventPayload) => void): DocAuthEditor;
  off(event: EventName, handler?: (payload: EventPayload) => void): DocAuthEditor;
  once(event: EventName, handler: (payload: EventPayload) => void): DocAuthEditor;
}

The visual editor UI. Binds to a DOM element and lets users edit documents.

Create editors using createDocAuthSystem.

Methods

setCurrentDocument()

setCurrentDocument(doc): void

Attaches the provided document as the current document to the editor.

Parameters

doc

DocAuthDocument

Returns

void

---

currentDocument()

currentDocument(): DocAuthDocument

Returns a reference to the currently attached document.

Returns

DocAuthDocument

---

destroy()

destroy(): void

Removes all DOM elements and releases resources held by the editor. Note: This does not release the underlying DocAuthSystem. Use DocAuthSystem.destroy after calling DocAuthEditor.destroy for a complete teardown.

Returns

void

---

docAuthSystem()

docAuthSystem(): DocAuthSystem

Retrieves the DocAuthSystem instance this editor is bound to.

Returns

DocAuthSystem

---

hasActiveCursor()

>= v1.9.0

hasActiveCursor(): boolean

Checks if the editor has an active cursor/insertion point. This is useful for custom actions to determine if they should be enabled.

Returns

boolean

True if cursor is active and insertion is possible, false otherwise

---

insertTextAtCursor()

>= v1.9.0

insertTextAtCursor(text): void

Inserts text at the current cursor position. If there’s a selection, it will be replaced with the provided text.

Deprecated

Use insertContentAtCursor with { content } (or { format: 'text', content }) instead.

Parameters

text

string

The text to insert at the cursor position

Returns

void

---

insertContentAtCursor()

>= v1.15.0

insertContentAtCursor(options): void

Inserts content at the current cursor position. If there’s a range selection, it will be replaced. If there is no active cursor, this is a silent no-op.

format is the same discriminator used by getSelectionContent, so a fragment captured from the editor round-trips back through this method.

• { content: string } (format defaults to 'text') inserts the given string. Newlines become paragraph breaks via the same logic as paste.
• { format: 'fragment', content: object } inserts a structured fragment. Throws a tagged DocAuthError if the fragment is malformed — detect with isDocAuthError or one of the per-type guards (isInvalidFragmentTypeError, isUnsupportedFragmentVersionError, isMissingFragmentContentError).

Parameters

options

InsertContentAtCursorOptions

The content to insert, discriminated by format. See InsertContentAtCursorOptions.

Returns

void

Example

import { isUnsupportedFragmentVersionError, isDocAuthError } from '@nutrient-sdk/document-authoring';

editor.insertContentAtCursor({ content: 'hello' });

const fragment = editor.getSelectionContent({ format: 'fragment' });
if (!fragment) return;
const transformed = await sendToModel(fragment);
try {
    editor.insertContentAtCursor({ format: 'fragment', content: transformed });
} catch (err) {
    if (isUnsupportedFragmentVersionError(err)) {
        console.error(`Need version ${err.expected}, got ${err.actual}`);
    } else if (isDocAuthError(err)) {
        console.error(err.type, err.message);
    }
}

---

getSelectionContent()

>= v1.15.0

getSelectionContent<F>(options): SelectionContentByFormat[F] | null

Returns the current selection in the requested format, or null if there is no range selection.

• format: 'text' returns the selected text as a plain string.
• format: 'fragment' returns a structured fragment object that round-trips through insertContentAtCursor with format: 'fragment'. Treat as opaque JSON-serializable data; don’t depend on its internal shape.

A collapsed cursor (zero-width caret) returns null for either format. Use hasActiveCursor to distinguish a collapsed cursor from a missing one.

Type Parameters

F

F extends SelectionContentFormat

Parameters

options

The format to read the selection in. See SelectionContentFormat.

format

F

Returns

SelectionContentByFormat[F] | null

The selection in the requested format, or null if no range is selected.

Example

const text = editor.getSelectionContent({ format: 'text' });
if (text !== null) console.log('Selected:', text);

const fragment = editor.getSelectionContent({ format: 'fragment' });
if (fragment !== null) editor.insertContentAtCursor({ format: 'fragment', content: fragment });

---

setActions()

>= v1.9.0

setActions(actions): void

Set all actions (replaces any existing actions). Allows setting and executing editor actions programmatically.

Parameters

actions

Action[]

Array of actions to register

Returns

void

Example

import { defaultActions } from '@nutrient-sdk/document-authoring';

// Register custom actions alongside default actions
editor.setActions([
  ...defaultActions, // Keep default actions
  {
    id: 'custom.insert-signature',
    label: 'Insert Signature',
    handler: () => {
      editor.insertTextAtCursor('\n\nBest regards,\nJohn Doe');
    },
    shortcuts: ['Mod+Shift+S'],
  },
]);

---

setToolbarConfig()

>= v1.9.0

setToolbarConfig(config): void

Set the toolbar configuration. Use this to customize the editor’s toolbar.

Parameters

config

ToolbarConfig

Toolbar configuration object

Returns

void

Example

import { defaultToolbarConfig } from '@nutrient-sdk/document-authoring';

// Use default toolbar config but add a custom item
editor.setToolbarConfig({
  ...defaultToolbarConfig,
  items: [...defaultToolbarConfig.items, { type: 'action', id: 'custom', actionId: 'custom.insert-signature' }],
});

// Or create a minimal toolbar
editor.setToolbarConfig({
  ...defaultToolbarConfig,
  items: [
    { type: 'built-in', id: 'undo', builtInType: 'undo' },
    { type: 'built-in', id: 'redo', builtInType: 'redo' },
    { type: 'separator', id: 'sep-1' },
    { type: 'built-in', id: 'bold', builtInType: 'bold' },
    { type: 'built-in', id: 'italic', builtInType: 'italic' },
    { type: 'action', id: 'custom', actionId: 'custom.insert-signature' },
  ],
});

---

setEditorMode()

>= v1.13.0

setEditorMode(mode): void

Sets the current editor mode.

Parameters

mode

DocAuthEditorMode

The editor mode to use.

Returns

void

---

getEditorMode()

>= v1.13.0

getEditorMode(): DocAuthEditorMode

Returns the current editor mode.

Returns

DocAuthEditorMode

---

setAuthor()

>= v1.10.0

setAuthor(name): void

Sets the author name used when creating comments, replies, and tracked changes.

Parameters

name

string

The author name to use for new comments

Returns

void

Example

// Set author when user logs in
editor.setAuthor('John Doe');

// Clear author when user logs out (will use localized "Anonymous")
editor.setAuthor('');

See

UIOptions.author for setting the initial author.

---

getAuthor()

>= v1.13.0

getAuthor(): string

Returns the author name used when creating comments, replies, and tracked changes.

Returns

string

---

enableSpellcheck()

>= v1.13.0

enableSpellcheck(language): void

Enables spell checking for the given language. Returns immediately; misspelled words begin to be underlined shortly after, once the dictionary has loaded. Also works to switch from one language to another — call again with a different language at any time.

Parameters

language

SpellcheckLanguage

The spellcheck language to activate.

Returns

void

Example

editor.enableSpellcheck('fr-FR');
editor.enableSpellcheck('en-US');

See

• editor.disableSpellcheck() to turn spell checking off.
• UIOptions.spellcheck for setting the initial language.

---

disableSpellcheck()

>= v1.13.0

disableSpellcheck(): void

Disables spell checking. Removes any misspelled-word underlines currently drawn and stops checking new edits. Safe to call when spell checking is already off.

Returns

void

Example

editor.disableSpellcheck();

See

editor.enableSpellcheck() to turn spell checking on.

---

on()

>= v1.8.0

on(event, handler): DocAuthEditor

Adds an event listener that will be called every time the specified event is emitted.

Parameters

event

EventName

handler

(payload: EventPayload) => void

Returns

DocAuthEditor

The editor instance for method chaining

Example

// Auto-save on content changes
editor.on('content.change', async () => {
  const doc = await editor.currentDocument().saveDocument();
  localStorage.setItem('draft', JSON.stringify(doc));
});

// Track document load
editor.on('document.load', () => {
  console.log('Document loaded successfully');
});

// Debounced save to prevent excessive API calls
let saveTimeout;
editor.on('content.change', async () => {
  clearTimeout(saveTimeout);
  saveTimeout = setTimeout(async () => {
    const doc = await editor.currentDocument().saveDocument();
    await fetch('/api/save', {
      method: 'POST',
      body: JSON.stringify(doc),
    });
  }, 1000);
});

// Method chaining
editor.on('document.load', () => console.log('loaded')).on('content.change', () => console.log('changed'));

Available Events

Event name	Event payload	Description
document.load	none	Fired when a document is initially loaded into the editor. This event is triggered once per document load, including when switching documents.
content.change	none	Fired when the document content has changed due to user editing or programmatic modifications. Use this event to react to document changes, such as saving drafts or updating UI state.

---

off()

>= v1.8.0

off(event, handler?): DocAuthEditor

Removes an event listener. If no handler is provided, removes all listeners for the event.

Parameters

event

EventName

handler?

(payload: EventPayload) => void

Returns

DocAuthEditor

The editor instance for method chaining

Example

// Remove specific handler (prevent memory leaks)
const handleChange = async () => {
  const doc = await editor.currentDocument().saveDocument();
  localStorage.setItem('draft', JSON.stringify(doc));
};
editor.on('content.change', handleChange);
// ... later ...
editor.off('content.change', handleChange);

// Remove all handlers for an event
editor.off('content.change');

// Cleanup pattern
const setupEditor = (target) => {
  const editor = await system.createEditor(target);

  const handleChange = () => console.log('changed');
  const handleLoad = () => console.log('loaded');

  editor.on('content.change', handleChange);
  editor.on('document.load', handleLoad);

  return () => {
    editor.off('content.change', handleChange);
    editor.off('document.load', handleLoad);
    editor.destroy();
  };
};

Available Events

Event name	Event payload	Description
document.load	none	Fired when a document is initially loaded into the editor. This event is triggered once per document load, including when switching documents.
content.change	none	Fired when the document content has changed due to user editing or programmatic modifications. Use this event to react to document changes, such as saving drafts or updating UI state.

---

once()

>= v1.8.0

once(event, handler): DocAuthEditor

Adds an event listener that will be called only once when the specified event is emitted. The listener is automatically removed after being called.

Parameters

event

EventName

handler

(payload: EventPayload) => void

Returns

DocAuthEditor

The editor instance for method chaining

Example

// Wait for initial document load
editor.once('document.load', () => {
  console.log('Document loaded for the first time');
});

// Perform action after first change
editor.once('content.change', () => {
  console.log('User made their first edit');
});

// Promise-based pattern for waiting on load
const waitForLoad = (editor) => {
  return new Promise((resolve) => {
    editor.once('document.load', resolve);
  });
};
await waitForLoad(editor);
console.log('Ready to use');

Available Events

Event name	Event payload	Description
document.load	none	Fired when a document is initially loaded into the editor. This event is triggered once per document load, including when switching documents.
content.change	none	Fired when the document content has changed due to user editing or programmatic modifications. Use this event to react to document changes, such as saving drafts or updating UI state.