DocAuthEditor

DocAuthEditor:

{
  setCurrentDocument(doc: DocAuthDocument): void;
  currentDocument(): DocAuthDocument;
  navigateTo(location: DocumentLocation): Promise<NavigateResult>;
  addVisualHighlight(location: DocumentLocation, options?: Readonly<{ color?: string; opacity?: number }>): Promise<AddVisualHighlightResult>;
  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;
  isActionRegistered(id: string): boolean;
  isActionEnabled(id: string): boolean;
  executeAction(call: ActionCall): Promise<void>;
  setToolbarConfig(config: ToolbarConfig): void;
  setContextMenuConfig(config: ContextMenuConfig): void;
  setEditorMode(mode: DocAuthEditorMode): void;
  getEditorMode(): DocAuthEditorMode;
  setZoom(factor: number): void;
  getZoom(): number;
  setAuthor(name: string): void;
  getAuthor(): string;
  enableSpellcheck(language: SpellcheckLanguage): void;
  disableSpellcheck(): void;
  find: FindNamespace;
  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.

Properties

find

>= v1.19.0

find: FindNamespace

The Find namespace. Searches the document and provides programmatic control over the editor’s Find bar.

See

FindNamespace

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

navigateTo()

>= v1.22.0

navigateTo(location): Promise<NavigateResult>

Reveals a portable document location without changing the current selection or focus.

Parameters

location

DocumentLocation

A location created for the current saved document.

Returns

Promise<NavigateResult>

A tagged result describing whether the location was revealed.

addVisualHighlight()

>= v1.22.0

addVisualHighlight(location, options?): Promise<AddVisualHighlightResult>

Adds a visual highlight to a ranged portable document location.

This method does not scroll, focus, select, or change document content. The SDK removes visual highlights when the document changes; hosts can remove one sooner through the returned handle.

Parameters

location

DocumentLocation

A ranged location created for the current saved document.

options?

Readonly<{ color?: string; opacity?: number; }>

Optional highlight color and opacity.

Returns

Promise<AddVisualHighlightResult>

A tagged result containing a removable highlight when successful.

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.

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. Before importing resources or changing the document or selection, the SDK validates the complete value against the generated contract returned by DocAuthSystem.getFragmentContract. Invalid type tags, persistence versions, and missing content keep their tagged DocAuthError values — detect them with isDocAuthError or one of the per-type guards (isInvalidFragmentTypeError, isUnsupportedFragmentVersionError, isMissingFragmentContentError). Other contract violations also throw before mutation; call DocAuthSystem.validateFragment first when structured issues are needed.

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. The actions stay in effect when DocAuthEditor.setCurrentDocument switches documents.

Built-in toolbar controls and context menu items backed by a built-in action run it from this list, so a replacement with the same ID runs from them. A control or item whose action is left out is hidden, and one whose action can’t run is disabled.

Each action’s capabilities decide which editor modes it can run in. See BuiltInAction and CustomAction for the defaults, and DocAuthEditorMode for what each mode allows.

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'],
  },
]);

isActionRegistered()

isActionRegistered(id): boolean

Returns true if an action with this ID is registered on this editor. A registered action may still be disabled; see isActionEnabled().

Parameters

id

string

Returns

boolean

isActionEnabled()

isActionEnabled(id): boolean

Returns true if the action is registered and can run now.

Parameters

id

string

Returns

boolean

executeAction()

executeAction(call): Promise<void>

Executes a registered action, checking availability again at invocation time. Build calls to built-in actions with actionCalls, which types and documents their arguments. For a custom action, pass an ActionCall object.

Rejects with a TypeError if call is not an object with a string id and an args array. Rejects if the action is missing, unavailable, its arguments are invalid, or its handler fails. Resolves when the handler completes. The SDK validates arguments for built-in handlers. Custom and replacement handlers are responsible for validating their own arguments.

Parameters

call

ActionCall

The ID of the action and the arguments for its handler.

Returns

Promise<void>

Example

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

await editor.executeAction(actionCalls['formatting.bold'](true));
await editor.executeAction(actionCalls['formatting.font-size'](14));
await editor.executeAction(actionCalls['layout.page-margin']('l', 72)); // points
// Highlight takes an opaque hex color, 'none', or null.
await editor.executeAction(actionCalls['formatting.highlight-color']('#ffff00'));
// Clear, like the toolbar: no highlight, even where the text's style has one.
await editor.executeAction(actionCalls['formatting.highlight-color']('none'));
// Remove only the direct highlight; a highlight from the text's style shows again.
await editor.executeAction(actionCalls['formatting.highlight-color'](null));

// A custom action registered with setActions()
await editor.executeAction({ id: 'custom.save', args: ['/api/save'] });

setToolbarConfig()

>= v1.9.0

setToolbarConfig(config): void

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

The configuration stays in effect when DocAuthEditor.setCurrentDocument switches documents.

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' },
  ],
});

setContextMenuConfig()

>= v2.0.0

setContextMenuConfig(config): void

Set the items the host app adds to the editor’s context menus. Replaces any items set before. Host items come after the built-in items, which follow DocAuthEditor.setActions.

Parameters

config

ContextMenuConfig

Context menu configuration object

Returns

void

Example

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

editor.setActions([
  ...defaultActions,
  { id: 'custom.define', label: 'Look up definition', handler: () => showDefinition() },
]);

editor.setContextMenuConfig({
  text: { items: [{ type: 'action', id: 'define', actionId: 'custom.define' }] },
});

// Remove all host items
editor.setContextMenuConfig({});

setEditorMode()

>= v1.13.0

setEditorMode(mode): void

Sets the current editor mode. The mode decides which actions can run; see DocAuthEditorMode.

Parameters

mode

DocAuthEditorMode

The editor mode to use.

Returns

void

getEditorMode()

>= v1.13.0

getEditorMode(): DocAuthEditorMode

Returns the current editor mode.

Returns

DocAuthEditorMode

setZoom()

>= v1.21.0

setZoom(factor): void

Sets the zoom factor of the editor view. 1 means 100%, 0.5 means 50%.

Finite values are clamped to the supported range of 0.5 to 4 (50% to 400%), the same bounds the toolbar zoom control, the view.zoom-in / view.zoom-out shortcuts, and Ctrl+wheel zoom use. Non-finite values (NaN, Infinity) throw a RangeError and leave the zoom unchanged.

The change applies synchronously: page sizes are updated before this method returns, and editor.getZoom() immediately reflects the clamped value. Zoom is presentation state only. It does not modify the document, the saved output, the selection, or undo history, and it works in every editor mode, including view.

Zoom belongs to the editor view, not the document: editor.setCurrentDocument() rebuilds the view and resets zoom to the creation-time default (100% unless the host configured otherwise). Re-apply setZoom() after swapping documents if a different zoom is wanted.

Parameters

factor

number

The zoom factor to apply, where 1 is 100%. Clamped to 0.5..4.

Returns

void

Example

// Show the document at 50% in a narrow sidebar
editor.setZoom(0.5);

// Back to 100%
editor.setZoom(1);

Throws

RangeError when factor is not a finite number.

See

editor.getZoom() to read the current zoom.

getZoom()

>= v1.21.0

getZoom(): number

Returns the current zoom factor of the editor view, where 1 means 100%.

The value reflects every way zoom can change: editor.setZoom(), the toolbar zoom control, keyboard shortcuts, and Ctrl+wheel. It is always within 0.5..4. Values set from the toolbar are exact steps such as 1.25; wheel zoom can produce arbitrary fractions.

Returns

number

Example

const percent = Math.round(editor.getZoom() * 100);

See

editor.setZoom() to change the zoom.

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('');

The author stays in effect when DocAuthEditor.setCurrentDocument switches documents.

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. It is emitted before any `content.change` for that document. When the document was already laid out, for example because it was created some time before the editor, the event fires shortly after `createEditor` resolves or `setCurrentDocument` returns.
`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.
`selection.change`	none	Fired after the caret or selection changes, including when it is cleared. Read the updated state with getSelectionContent() and hasActiveCursor(). Adding a listener does not report the current selection, so read it once when you subscribe. Subscribe to content.change as well if selected content must stay up to date.
`tracked-change.lifecycle`	`{ operation: “create”; phase: “attempted"	"denied” }
`comment.lifecycle`	`{ operation: “create”; phase: “attempted” }	{ operation: “create”; phase: “completed”; commentId: string }
`revision.created`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are created.
`revision.edited`	`RevisionEventPayload`	Fired when one or more existing tracked-change revisions are edited.
`revision.accepted`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are accepted.
`revision.rejected`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are rejected.
`revision.withdrawn`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are withdrawn.
`comment.threadAdded`	`CommentEventPayload`	Fired when one or more comment threads are added.
`comment.replied`	`CommentEventPayload`	Fired when one or more replies are added to comment threads.
`comment.edited`	`CommentEventPayload`	Fired when the text of one or more comments or replies is edited.
`comment.resolved`	`CommentEventPayload`	Fired when one or more comment threads are resolved.
`comment.unresolved`	`CommentEventPayload`	Fired when one or more comment threads are marked unresolved.
`comment.removed`	`CommentEventPayload & { reason: “removed"	"anchor-deleted” }`
`content.change`	none	Fired after every committed transaction following document initialization.

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. It is emitted before any `content.change` for that document. When the document was already laid out, for example because it was created some time before the editor, the event fires shortly after `createEditor` resolves or `setCurrentDocument` returns.
`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.
`selection.change`	none	Fired after the caret or selection changes, including when it is cleared. Read the updated state with getSelectionContent() and hasActiveCursor(). Adding a listener does not report the current selection, so read it once when you subscribe. Subscribe to content.change as well if selected content must stay up to date.
`tracked-change.lifecycle`	`{ operation: “create”; phase: “attempted"	"denied” }
`comment.lifecycle`	`{ operation: “create”; phase: “attempted” }	{ operation: “create”; phase: “completed”; commentId: string }
`revision.created`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are created.
`revision.edited`	`RevisionEventPayload`	Fired when one or more existing tracked-change revisions are edited.
`revision.accepted`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are accepted.
`revision.rejected`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are rejected.
`revision.withdrawn`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are withdrawn.
`comment.threadAdded`	`CommentEventPayload`	Fired when one or more comment threads are added.
`comment.replied`	`CommentEventPayload`	Fired when one or more replies are added to comment threads.
`comment.edited`	`CommentEventPayload`	Fired when the text of one or more comments or replies is edited.
`comment.resolved`	`CommentEventPayload`	Fired when one or more comment threads are resolved.
`comment.unresolved`	`CommentEventPayload`	Fired when one or more comment threads are marked unresolved.
`comment.removed`	`CommentEventPayload & { reason: “removed"	"anchor-deleted” }`
`content.change`	none	Fired after every committed transaction following document initialization.

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. It is emitted before any `content.change` for that document. When the document was already laid out, for example because it was created some time before the editor, the event fires shortly after `createEditor` resolves or `setCurrentDocument` returns.
`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.
`selection.change`	none	Fired after the caret or selection changes, including when it is cleared. Read the updated state with getSelectionContent() and hasActiveCursor(). Adding a listener does not report the current selection, so read it once when you subscribe. Subscribe to content.change as well if selected content must stay up to date.
`tracked-change.lifecycle`	`{ operation: “create”; phase: “attempted"	"denied” }
`comment.lifecycle`	`{ operation: “create”; phase: “attempted” }	{ operation: “create”; phase: “completed”; commentId: string }
`revision.created`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are created.
`revision.edited`	`RevisionEventPayload`	Fired when one or more existing tracked-change revisions are edited.
`revision.accepted`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are accepted.
`revision.rejected`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are rejected.
`revision.withdrawn`	`RevisionEventPayload`	Fired when one or more tracked-change revisions are withdrawn.
`comment.threadAdded`	`CommentEventPayload`	Fired when one or more comment threads are added.
`comment.replied`	`CommentEventPayload`	Fired when one or more replies are added to comment threads.
`comment.edited`	`CommentEventPayload`	Fired when the text of one or more comments or replies is edited.
`comment.resolved`	`CommentEventPayload`	Fired when one or more comment threads are resolved.
`comment.unresolved`	`CommentEventPayload`	Fired when one or more comment threads are marked unresolved.
`comment.removed`	`CommentEventPayload & { reason: “removed"	"anchor-deleted” }`
`content.change`	none	Fired after every committed transaction following document initialization.