JavaScript API reference

Documentation index · Web quick start

Creation and conventions

For configuration, callback/event contracts and examples for registerTokens, registerSuggestions, setContextActions, configureReview, comments, proposals and getReviewPackage / loadReviewPackage, see Embedded content and editorial review. These APIs are part of the public editor instance. Their optional UI is included in the shared runtime assets.

const editor = CODEEditor.create(element, options);
// Equivalent after all scripts, in the asset manifest, have loaded:
const another = new CODEEditor.Editor(otherElement, otherOptions);

element is the editable surface container. Creation is synchronous; a ready event is queued as a microtask. Public operations are generally synchronous unless explicitly described as asynchronous. The WinForms bridge wraps them in asynchronous request/reply calls.

The read-only mode accessor reports source or rich. The accepted input alias visual means rich. Avoid assigning session, surface, or options internals directly to mutate a document; use the methods below. The internal helper methods visible on the JavaScript class are implementation details, not all separate host contracts.

Constructor options

Call setPreviewVisible(true) after creation to show the preview. A previewVisible value is a host-adapter option, not a general component constructor switch. Likewise findEnabled/replaceEnabled belong to the embedded control popup, not the bare JavaScript search API.

configure(options) supports presentation keys wrap, decorated, lineNumbers, tabIndents, tabWidth, indentWithTabs, typingRules, language, label, placeholder, fontFamily, fontSize, readOnly, theme; preview keys previewSync, previewSplit, previewCss, previewSyntaxHighlighting, onPreviewRequest; and policy keys preset, features, allowEmbeddedHtml, unsupportedContent, maxListDepth, headingLevels, allowSourceView. It does not load/convert formats or replace DOM elements. An empty label, fontFamily, or placeholder clears the previous display override. Omitted keys retain their values.

Document and lifecycle methods

setValue(value, 'source') is a legacy view shorthand; prefer the explicit options object. No method implicitly persists to a database or marks a document saved after a network call.

Selection, search and changes

Command-state enabled checks do not encode every structural/mode precondition. A command can be unavailable or reject even if the general enabled flag is true. Revision/session checks are detailed in the state guide.

Command names and arguments

Boolean mark names: bold, italic, underline, strike, code, superscript, subscript. Superscript and subscript replace each other. Other marks: href with safe URL or null, font with serif/mono/null, color with blue/green/purple/red/null, background with yellow/lightblue/lightgreen/plum/pink/null, size with 16/20/24/30/null. Null clears the override. Rich block types are p, h1–h6, ul, ol, task, quote, code, hr. Policy can prohibit any corresponding feature. All listed text formats except href are available as Markdown Source formatting commands. Omit value for boolean marks to toggle, or pass true/false for explicit on/off. With a caret, Source inserts paired markers or a style span; selecting Default for a style is a no-op at a caret. Foreground/background, font, size, underline and scripts require embedded HTML in Markdown. Their feature names are textColor, backgroundColor, fontFamily, fontSize, underline, superscript, subscript.

Markdown stores scripts as <sup>2</sup> / <sub>2</sub> and styles as <span style="font-family:serif;font-size:24px;color:red;background-color:yellow">text</span>. These remain editable in Visual mode, including nested supported spans. The curated font, size, and color choices are content formats; the fontFamily/fontSize editor options change display defaults instead.

Selection formatting and host toolbars

getSelectionFormatting() returns one snapshot for both views. formats maps inline mark/style names to { enabled, active }; blocks does the same for p, h1–h6, ul, ol, task, quote, code and hr. Boolean active states are true, false or "mixed". Styles return their value, false for no override, or "mixed". Disabled/read-only formatting can still be active. blockType is a block name or "mixed"; headingLevel is 1–6 or null. listType is ul/ol/task, "mixed" or null, and listDepth is a uniform zero-based depth or null. canIndent, canOutdent, canUndo, canRedo and readOnly are booleans. Queries do not change the document or history. Source projections are cached between edits.

Subscribe to commandStateChange; its selectionFormatting payload contains the snapshot. Refresh after cursor/selection moves, formatting, typing (including automatic input rules, list exits and typing marks), paste, undo/redo, loads, mode switches and policy/read-only changes. selectionChange is also available when only the logical position matters. In WinForms, use CommandStateChanged with the cached SelectionFormatting property; GetSelectionFormattingAsync() explicitly queries the same snapshot. Reading status in that handler does not generate another notification unless state actually changes.

editor.CommandStateChanged += (_, _) =>
{
    if (editor.SelectionFormatting is not { } state) return;
    var bold = state.GetFormat(TextMark.Bold);
    boldButton.Enabled = bold.Enabled;
    boldButton.CheckState = bold.IsMixed ? CheckState.Indeterminate
        : bold.IsActive ? CheckState.Checked : CheckState.Unchecked;
    indentButton.Enabled = state.CanIndent;
    outdentButton.Enabled = state.CanOutdent;
    headingLabel.Text = state.HeadingLevel is { } level ? $"Heading {level}" : state.BlockType;
};

queryCommandState(name) supports inline formats/styles, block names and indent/outdent. WinForms overloads accept TextMark, BlockStyle or EditorCommand. Execute list indentation through execute('indent') / execute('outdent') or ExecuteAsync(EditorCommand.Indent) / ExecuteAsync(EditorCommand.Outdent). Both views indent selected list items and their descendants; a preceding list item and available nesting depth are required to indent. Outdenting a top-level item returns it to a paragraph. In Source prose/code and Visual code blocks these commands instead indent/outdent literal lines. Changing block style through heading remains a Visual-mode operation.

Images and clipboard methods

pasteContent returning does not mean its images finished uploading. importImage handles an upload failure by leaving an error item; inspect image state rather than assuming resolution means ready. importExternalImage, cancelImports, and reconcileImages are lifecycle internals used by the import pipeline; prefer policy/callbacks and normal removal/loading to drive them.

Preview methods and hook

onPreviewRequest(request) can mutate or return { markdown?, html?, handled? }, synchronously or through a Promise. The request includes signal, format and session/version metadata. Handled requires an HTML string. Changing only the callback should be followed by refreshPreview() if immediate rendering is desired. See the preview chapter for full examples and isolation rules.

Events

Every emitted event includes type, sessionId, generation and revision. Additional fields depend on the event:

Events are not a transactional database log. External-image paths and file-image paths do not emit every lifecycle event identically; pendingImages and document state are authoritative. Unsubscribe handlers on host teardown and keep event handlers lightweight.

Image sizing/movement, toolbar placement, resource limits, review annotations and margin settings are described with examples in chapter 20.

UI styling: uiTheme / setUITheme(theme?) / getUITheme() provide instance-scoped CSS variables and stylesheet text; uiThemeChange signals a theme update. setCommentExpanded(id, expanded), toggleComment(id) and getCommentPresentation() control per-thread presentation without changing article state; commentPresentationChange carries id and expanded. Review options add singleOpen and commentMarkers. See the styling and bubble guide.

UI wording: uiStrings, setUIStrings(config?), getUIStrings() and getUIStringCatalog() configure per-instance text and accessibility labels. CODEEditor.getUIStringCatalog() is available before initialization; uiStringsChange reports updates. See UI wording and localization.

appearance, setAppearance(value = {}) and getAppearance() expose named host font, color and source spacing settings. See host appearance settings. Updates replace the overrides; an empty object restores theme defaults without document edits. imageToolbar configures the Visual image toolbar at creation or with configure({ imageToolbar }); see image toolbar configuration and image selection colors.

Native spellcheck

Spellcheck defaults to enabled for prose in Visual mode and Markdown/plain-text Source mode. Fenced snippets and inline code are excluded; Source views of programming languages and raw HTML are not checked. No dictionaries or word lists are shipped or maintained by the editor.

const editor = CODEEditor.create(element, {
  value: 'Write here',
  spellCheck: true,
  spellCheckLanguage: 'de-DE'
});
editor.configure({ spellCheck: false });
editor.configure({ spellCheck: true, spellCheckLanguage: 'es-ES' });

spellCheckLanguage is a language tag, independent of the language used for syntax highlighting. Examples: en-US, en-GB, de-DE, es-ES, fr-FR, it-IT, nl-NL, pt-PT. An empty string restores inherited language behavior. Language hints do not install dictionaries or override browser/OS proofing preferences. In particular, Chromium/WebView2 may ignore a changed HTML lang for spelling; configure browser/OS languages as needed. See WebView2 language limitation.

Right-click an underlined word to use the browser's native suggestions and dictionary/ignore actions, where provided by that browser/runtime. These actions and their wording are browser-owned; the editor does not provide a separate Ignore list or dictionary. Native spelling corrections enter the normal document history and change tracking. Websites should leave the native context menu enabled to retain this functionality.

Textblock preview and review switches

onTextblockPreviewRequest(request) expands registered token occurrences in preview; see textblock actions and preview for the request and native equivalent. reviewEnabled, commentsEnabled, and changeTrackingEnabled default to true and can change through configure; see disabling review features. language: 'xml' selects XML Source syntax independently of format.

Width options: maximumEditWidth: 900, maximumPreviewWidth: 900, restrictMaximumEditWidth: true, and restrictMaximumPreviewWidth: true. Widths are positive integer CSS pixels. Set either restriction to false to expand that pane. These options can also be changed through configure(); each pane centers its content independently.