Rich Text Editor API
Every public member of <oge-editor>, its config provider, the reactive-forms validator and the shared command vocabulary. Back to the demos →
Properties Methods Events Types
OgeEditor
oge-editorProperties 33
Value and forms
| Name | Type | Default | Description |
|---|---|---|---|
value | string | '' | The sanitized HTML value — two-way ([(value)]). The empty string when the document is empty. An external value is parsed through the editor’s allowlist; the editor ignores its own echo, so the caret and the history survive two-way binding. |
disabled | boolean | false | Not editable and out of the Tab order (aria-disabled). Reactive forms’ disable() sets it too. |
readonly | boolean | false | Focusable and selectable, but not editable (aria-readonly); every tool is disabled. |
required | boolean | false | Sets aria-required and the asterisk. Validation itself comes from the form (Validators.required, Signal Forms required()). |
name | string | '' | Written as data-name on the editing surface. |
invalid | boolean | false | External invalid override, combined with the forms state. |
touched / dirty | boolean | false | Signal Forms contract inputs; errors show once the field is touched. |
errors | readonly OgeFieldError[] | [] | Signal Forms validation errors (bound by [formField]). |
maxLength | number | undefined | undefined | Most characters (grapheme clusters) of text the document may hold. Typing and pasting stop there (announced), the counter shows the budget, and a longer external value shows the error. |
Chrome
| Name | Type | Default | Description |
|---|---|---|---|
label | string | '' | Visible label above the editor; also its accessible name (aria-labelledby). |
ariaLabel | string | undefined | undefined | Accessible name when there is no visible label; falls back to messages.editorLabel. |
placeholder | string | '' | Shown while the document is empty; also aria-placeholder. |
hint | string | undefined | undefined | Helper text under the editor, hidden while an error shows; part of aria-describedby. |
errorText | string | undefined | undefined | Explicit error message — always wins over the resolved messages. |
counter | 'none' | 'characters' | 'words' | 'both' | 'none' | Character / word counter under the editor (ICU plurals from messages.counter). With maxLength the character count reads 12 / 200. |
toolbar | readonly OgeEditorToolbarEntry[] | false | undefined | undefined | Toolbar entries: built-in tool names, 'separator' and OgeEditorCustomTool objects. undefined is the full default toolbar, false hides it. |
toolbarOverflow | 'menu' | 'scroll' | 'wrap' | 'extended' | 'none' | 'menu' | What the toolbar does with tools that do not fit (the layout toolbar’s overflow). |
height / minHeight / maxHeight | number | string | undefined | undefined | Size of the editing area — a number is px, a string any CSS length. Without them the area starts at 160px and grows with its content. |
resizable | boolean | false | Adds a vertical resize handle to the editing area. |
spellcheck | boolean | true | The browser’s spell checking on the editing surface. |
tabIndex | number | 0 | Tab index of the editing surface. |
autofocus | boolean | false | Focuses the editor after its first render. |
id | string | undefined | undefined | Base of the generated element ids (content, label, hint, error, counter). |
Behaviour (undefined = config)
| Name | Type | Default | Description |
|---|---|---|---|
markdownShortcuts | boolean | undefined | true | # …###### , - , 1. , > , ``` at the start of a paragraph and --- + Enter turn into formats. One undo brings the typed characters back. |
pasteMode | 'html' | 'text' | undefined | 'html' | 'html' keeps (sanitized) formatting from the clipboard; 'text' inserts text only. |
headingLevels | readonly OgeEditorHeadingLevel[] | undefined | [1, 2, 3, 4] | Heading levels the block-format menu offers. |
textColors / backgroundColors | OgeColorPalettePreset | readonly string[] | undefined | 'default' | Palettes of the two colour popups — an @oge-ui/inputs palette preset or your own colour list. Colours are validated (no url(), var() or expressions). |
allowedSchemes | readonly string[] | undefined | [] | Extra link schemes on top of sanitizeUrl’s allowlist (http, https, mailto, tel, ftp, sms). Script schemes can never be allowed. |
allowDataImages | boolean | undefined | false | Keep data:image/* sources (PNG, JPEG, GIF, WebP, AVIF, BMP — never SVG). blob: and file: images are always dropped. |
messages | OgeEditorMessagesInput | undefined | undefined | Per-instance overrides of the user-facing strings, merged group by group over the config. |
Read-only state
| Name | Type | Default | Description |
|---|---|---|---|
activeState | Signal<OgeEditorActiveState> | — | The formats under the selection — what the toolbar shows (marks, block format, list, alignment, link, colours). |
characterCount / wordCount | Signal<number> | — | Grapheme clusters and words (Intl.Segmenter) of the text. |
canUndo / canRedo | Signal<boolean> | — | Whether the history has a step back / forward. |
Methods 14
| Name | Type | Description |
|---|---|---|
focus() | void | Moves focus into the editing area and restores the caret. |
blur() | void | Removes keyboard focus. |
exec(command) | (command: OgeEditorCommandName | OgeEditorCommand) => boolean | Runs a command — a name ('bold', 'heading2', 'bulletList'…) or a command object ({ type: 'color', color: '#c00' }). Returns true when it changed something. |
undo() / redo() | () => boolean | Steps through the editor’s own history. |
insertText(text) | (text: string) => void | Inserts plain text at the selection (newlines become paragraphs). |
insertHtml(html) | (html: string) => void | Inserts HTML at the selection — parsed through the editor’s allowlist first, like a paste. |
insertLink(href, text?, newTab?) | (href: string, text?: string, newTab?: boolean) => boolean | Links the selection, or inserts text (default: the address) as a link. Unsafe addresses are refused (false); new-tab links get rel="noopener noreferrer". |
removeLink() | () => boolean | Removes the link under the selection or around the caret. |
insertImage(src, alt?) | (src: string, alt?: string) => boolean | Inserts an image by URL; unsafe sources are refused. |
selectAll() | void | Selects the whole document. |
getHtml() / getText() | () => string | The current value, or its text with blocks separated by newlines. |
clear() | void | Empties the editor as one undoable change. |
reset(value?) | (value?: string) => void | Loads value (default: empty), clears the history and the touched / dirty state; on a reactive-forms binding it resets the control. |
openLinkDialog() / openImageDialog() | () => Promise<void> | Opens the link or image prompt for the selection (also Ctrl+K and the toolbar tools), subject to dialogOpening. |
Events 8
| Name | Type | Description |
|---|---|---|
valueCommitted | OgeEditorValueCommittedEvent | Every committed change: { value, previousValue, event }. |
focused / blurred | OgeEditorFocusEvent | Focus entered or left the editor (popups included). |
touch | void | Signal Forms FormValueControl contract — once per blur. |
selectionChanged | OgeEditorSelectionChangedEvent | The selection moved or its formats changed: { active }. |
commandExecuted | OgeEditorCommandExecutedEvent | A command ran (keyboard, toolbar or exec): { command, event }. |
toolClick | OgeEditorToolClickEvent | A toolbar tool was activated: { key, inMenu, event }. |
pasting | OgeEditorPastingEvent | Cancelable: a paste or drop is about to be inserted. Set cancel, or rewrite html / text. |
dialogOpening | OgeEditorDialogOpeningEvent | Cancelable: the link or image dialog is about to open ({ kind, link, cancel }). Cancel it to show your own dialog, then call insertLink() / insertImage(). |
Types 15
| Name | Type | Description |
|---|---|---|
OgeEditorToolName | 'undo' | 'redo' | 'blockFormat' | 'bold' | 'italic' | 'underline' | 'strike' | 'code' | 'subscript' | 'superscript' | 'textColor' | 'backgroundColor' | 'link' | 'unlink' | 'image' | 'bulletList' | 'orderedList' | 'indent' | 'outdent' | 'blockquote' | 'codeBlock' | 'horizontalRule' | 'alignStart' | 'alignCenter' | 'alignEnd' | 'alignJustify' | 'directionLtr' | 'directionRtl' | 'clearFormatting' | Built-in toolbar tools. OGE_DEFAULT_EDITOR_TOOLBAR is the default arrangement. |
OgeEditorToolbarEntry | OgeEditorToolName | 'separator' | OgeEditorCustomTool | One toolbar entry. Leading, trailing and doubled separators are dropped. |
OgeEditorCustomTool | { key; text; icon?; hint?; shortcut?; isActive?(active); isDisabled?(active); run(context: OgeEditorToolContext) } | A tool of your own. isActive makes it a toggle (aria-pressed); run receives exec, insertHtml, insertText, getHtml and the active state. |
OgeEditorCommandName | 'bold' | 'italic' | … | 'heading1'…'heading6' | 'blockquote' | 'codeBlock' | 'bulletList' | 'orderedList' | 'indent' | 'outdent' | 'alignStart' | 'alignCenter' | 'alignEnd' | 'alignJustify' | 'horizontalRule' | 'clearFormatting' | 'unlink' | 'undo' | 'redo' | 'selectAll' | Parameterless commands by name, for exec(). |
OgeEditorCommand | { type: 'toggleMark'; mark } | { type: 'blockFormat'; format; level? } | { type: 'list'; list } | { type: 'align'; align } | { type: 'color' | 'background'; color } | { type: 'link'; href; text?; newTab? } | { type: 'image'; src; alt? } | … | A command object — the same vocabulary the toolbar and the keyboard map issue. |
OgeEditorActiveState | { marks; blockFormat; list; align; dir; link; color; background; canIndent; canOutdent; collapsed } | What the selection currently is. |
OgeEditorMessages | interface | Every user-facing string: tool names, block names, dialogs, colours, counter (ICU plurals), announcements, validation and key names. Translated in all ten @oge-ui/locales packs. |
provideOgeEditorConfig(config) | (config: OgeEditorConfigInput | (() => OgeEditorConfigInput)) => Provider | App- or route-wide defaults and strings; a function makes them live. |
ogeEditorMaxLength(max) | (max: number, options?: OgeEditorParseOptions) => ValidatorFn | Reactive-forms validator that counts the text of the HTML value — Validators.maxLength would count the markup. Reports { ogeEditorMaxLength: { max, actual } }. |
ogeSanitizeEditorHtml(html, options?) | (html: string | null | undefined, options?: OgeEditorParseOptions) => string | The editor’s allowlist as a function — for values that did not come through the editor. Only the editor’s own tags and attributes come out. Works on a server too: without DOMParser the editor’s own tokenizer reads the markup (the same one that server-renders the editing surface). |
ogeEditorHtmlLength(html) | (html: string | null | undefined, options?: OgeEditorParseOptions) => number | Characters of an HTML value’s text — the measure maxLength applies. |
ogeEditorCommandFromName(name) | (name: OgeEditorCommandName) => OgeEditorCommand | Expands a command name into its command object. |
OGE_EDITOR_TRUSTED_TYPES_POLICY | 'oge-ui#editor' | Name of the Trusted Types policy behind the editor’s one DOMParser call. List it in a trusted-types CSP directive. |
OGE_EDITOR_CONFIG / OGE_DEFAULT_EDITOR_CONFIG / OGE_DEFAULT_EDITOR_MESSAGES | InjectionToken<OgeEditorConfig> / OgeEditorConfig / OgeEditorMessages | The config token every editor reads, and the shipped defaults. |
OGE_DEFAULT_EDITOR_TOOLBAR | readonly OgeEditorToolbarEntry[] | The default toolbar arrangement — spread it to extend the default instead of replacing it. |