Skip to main content

@lexical/a11y

Interfaces​

AriaLiveRegionExtensionConfig​

Defined in: packages/lexical-a11y/src/index.ts:535

Properties​

owner​

owner: HTMLElement | null

Defined in: packages/lexical-a11y/src/index.ts:543

Owner element to append the live region to. null falls back to document.body; an explicit element keeps the region in the same accessibility subtree as the editor (shadow root or portaled overlay).

politeness​

politeness: AriaPoliteness

Defined in: packages/lexical-a11y/src/index.ts:537

AriaPoliteness for the mounted region.

AriaLiveRegionHandle​

Defined in: packages/lexical-a11y/src/index.ts:39

Properties​

announce​

announce: (message) => void

Defined in: packages/lexical-a11y/src/index.ts:45

Write a message into the live region. Calling with the same string back-to-back appends a zero-width space so screen readers register the change and re-announce.

Parameters​
message​

string

Returns​

void

dispose​

dispose: () => void

Defined in: packages/lexical-a11y/src/index.ts:50

Remove the live region element from its owner. Safe to call more than once.

Returns​

void

AriaLiveRegionOptions​

Defined in: packages/lexical-a11y/src/index.ts:23

Properties​

owner?​

optional owner?: HTMLElement

Defined in: packages/lexical-a11y/src/index.ts:36

Owner element to append the live region to. Defaults to document.body. Passing a specific element keeps the region in the same accessibility subtree as the editor when the editor lives inside a shadow root or a portaled overlay.

politeness?​

optional politeness?: AriaPoliteness

Defined in: packages/lexical-a11y/src/index.ts:29

How insistently the screen reader announces updates.

  • polite (default): announce after the current speech completes.
  • assertive: interrupt the current speech.

AriaLiveRegionRef​

Defined in: packages/lexical-a11y/src/index.ts:554

Stable handle ref shared between AriaLiveRegionExtension and its dependents. The register step swaps current to a live handle for the editor's lifetime and restores NOOP_HANDLE on disposal, so dependent extensions can capture the ref in build while the actual sink is created without violating the "build must not require cleanup" contract.

Properties​

current​

current: AriaLiveRegionHandle

Defined in: packages/lexical-a11y/src/index.ts:555

EditorModeAnnounceExtensionConfig​

Defined in: packages/lexical-a11y/src/index.ts:623

Properties​

editable​

editable: string

Defined in: packages/lexical-a11y/src/index.ts:625

Message announced when the editor becomes editable.

readOnly​

readOnly: string

Defined in: packages/lexical-a11y/src/index.ts:627

Message announced when the editor becomes read-only.

EditorModeAnnounceOptions​

Defined in: packages/lexical-a11y/src/index.ts:506

Properties​

editable?​

optional editable?: string

Defined in: packages/lexical-a11y/src/index.ts:508

Message announced when the editor becomes editable. Default: 'Editor is editable'.

readOnly?​

optional readOnly?: string

Defined in: packages/lexical-a11y/src/index.ts:510

Message announced when the editor becomes read-only. Default: 'Editor is read-only'.

FocusManagerExtensionConfig​

Defined in: packages/lexical-a11y/src/index.ts:739

Properties​

toolbar​

toolbar: HTMLElement | null

Defined in: packages/lexical-a11y/src/index.ts:745

Toolbar element receiving the Alt+F10 jump from the editor and the Escape return back to the editor. null keeps the manager inert; supply a signal-backed ref to activate when the toolbar mounts.

toolbarItemSelector​

toolbarItemSelector: string | null

Defined in: packages/lexical-a11y/src/index.ts:750

Custom CSS selector for the toolbar's first focusable item. null falls back to the helper's default.

FocusManagerOptions​

Defined in: packages/lexical-a11y/src/index.ts:384

Properties​

toolbarItemSelector?​

optional toolbarItemSelector?: string

Defined in: packages/lexical-a11y/src/index.ts:391

Selector used to find the toolbar's first focusable item when activating via the shortcut. Defaults to non-disabled direct-child buttons (the same scope used by registerRovingTabIndex), so the active roving item naturally receives focus.

FocusTrapExtensionConfig​

Defined in: packages/lexical-a11y/src/index.ts:655

Properties​

container​

container: HTMLElement | null

Defined in: packages/lexical-a11y/src/index.ts:661

Container element to trap focus inside. null deactivates the trap; React adapters supply a signal-backed ref so modal open / close swaps the value at runtime and the effect re-registers.

initialFocus​

initialFocus: FocusTrapInitialFocus

Defined in: packages/lexical-a11y/src/index.ts:663

FocusTrapInitialFocus for the activation-time landing.

FocusTrapOptions​

Defined in: packages/lexical-a11y/src/index.ts:140

Properties​

initialFocus?​

optional initialFocus?: FocusTrapInitialFocus

Defined in: packages/lexical-a11y/src/index.ts:151

Where to land focus when the trap activates:

  • 'firstFocusable' (default): focus the first focusable descendant.
  • 'container': focus the container itself. The container must satisfy tabIndex >= -1; callers typically set tabIndex={-1} to keep it out of the natural Tab order while remaining programmatically focusable. Use for dialogs whose first focusable is a dismiss/close action so the user lands on the dialog body and screen readers announce the dialog label before any control.

HistoryAnnounceExtensionConfig​

Defined in: packages/lexical-a11y/src/index.ts:592

Properties​

redone​

redone: string

Defined in: packages/lexical-a11y/src/index.ts:596

Message announced after a redo.

undone​

undone: string

Defined in: packages/lexical-a11y/src/index.ts:594

Message announced after an undo.

HistoryAnnounceOptions​

Defined in: packages/lexical-a11y/src/index.ts:459

Properties​

redone?​

optional redone?: string

Defined in: packages/lexical-a11y/src/index.ts:463

Message announced after a redo. Default: 'Redone'.

undone?​

optional undone?: string

Defined in: packages/lexical-a11y/src/index.ts:461

Message announced after an undo. Default: 'Undone'.

RovingTabIndexExtensionConfig​

Defined in: packages/lexical-a11y/src/index.ts:693

Properties​

container​

container: HTMLElement | null

Defined in: packages/lexical-a11y/src/index.ts:699

Container element for the roving group. null keeps the extension inert; supply a signal-backed ref to activate when the toolbar mounts.

itemSelector​

itemSelector: string | null

Defined in: packages/lexical-a11y/src/index.ts:706

Custom CSS selector for items. null falls back to the helper's default (:scope > button:not([disabled])).

orientation​

orientation: RovingOrientation

Defined in: packages/lexical-a11y/src/index.ts:701

RovingOrientation for arrow-key navigation.

RovingTabIndexOptions​

Defined in: packages/lexical-a11y/src/index.ts:264

Properties​

itemSelector?​

optional itemSelector?: string

Defined in: packages/lexical-a11y/src/index.ts:277

Selector for the group's roving items. The default matches direct-child non-disabled buttons. Pass a custom selector to include other focusables or to scope to a marker attribute (e.g. [data-roving-item]).

orientation?​

optional orientation?: RovingOrientation

Defined in: packages/lexical-a11y/src/index.ts:271

Which arrow keys move focus.

  • horizontal (default): ArrowLeft / ArrowRight
  • vertical: ArrowUp / ArrowDown
  • both: any arrow key

Type Aliases​

AriaPoliteness​

AriaPoliteness = "polite" | "assertive"

Defined in: packages/lexical-a11y/src/index.ts:21

FocusTrapInitialFocus​

FocusTrapInitialFocus = "firstFocusable" | "container"

Defined in: packages/lexical-a11y/src/index.ts:138

RovingOrientation​

RovingOrientation = "horizontal" | "vertical" | "both"

Defined in: packages/lexical-a11y/src/index.ts:262

Variables​

AriaLiveRegionExtension​

const AriaLiveRegionExtension: LexicalExtension<AriaLiveRegionExtensionConfig, "@lexical/a11y/AriaLiveRegion", AriaLiveRegionRef, unknown>

Defined in: packages/lexical-a11y/src/index.ts:569

Platform-independent extension that owns a single aria-live region for the editor and exposes a stable AriaLiveRegionRef as the extension output. Other a11y extensions (HistoryAnnounceExtension, EditorModeAnnounceExtension) take this as a dependency and announce through output.current.announce.

Mount / dispose happens in register (the "build must not require cleanup" contract); the ref's current is swapped to the live handle there and restored to NOOP_HANDLE on disposal.

EditorModeAnnounceExtension​

const EditorModeAnnounceExtension: LexicalExtension<EditorModeAnnounceExtensionConfig, "@lexical/a11y/EditorModeAnnounce", NamedSignalsOutput<EditorModeAnnounceExtensionConfig>, unknown>

Defined in: packages/lexical-a11y/src/index.ts:635

Platform-independent extension that announces editor.setEditable(true|false) transitions through the AriaLiveRegionExtension's shared sink.

FocusManagerExtension​

const FocusManagerExtension: LexicalExtension<FocusManagerExtensionConfig, "@lexical/a11y/FocusManager", NamedSignalsOutput<FocusManagerExtensionConfig>, unknown>

Defined in: packages/lexical-a11y/src/index.ts:759

Platform-independent extension that wires the editor-to-toolbar focus jump (Alt+F10 / Escape return). Hosts using @lexical/extension supply the toolbar via the config signal; the React adapter is useLexicalFocusManager from @lexical/react.

FocusTrapExtension​

const FocusTrapExtension: LexicalExtension<FocusTrapExtensionConfig, "@lexical/a11y/FocusTrap", NamedSignalsOutput<FocusTrapExtensionConfig>, unknown>

Defined in: packages/lexical-a11y/src/index.ts:674

Platform-independent extension that traps Tab / Shift+Tab focus inside a container while it is non-null. Hosts using @lexical/extension swap the container config value (typically via configExtension or a signal-backed ref) to activate / deactivate the trap; the React adapter is useLexicalFocusTrap from @lexical/react.

HistoryAnnounceExtension​

const HistoryAnnounceExtension: LexicalExtension<HistoryAnnounceExtensionConfig, "@lexical/a11y/HistoryAnnounce", NamedSignalsOutput<HistoryAnnounceExtensionConfig>, unknown>

Defined in: packages/lexical-a11y/src/index.ts:603

Platform-independent extension that announces undo / redo through the AriaLiveRegionExtension's shared sink.

RovingTabIndexExtension​

const RovingTabIndexExtension: LexicalExtension<RovingTabIndexExtensionConfig, "@lexical/a11y/RovingTabIndex", NamedSignalsOutput<RovingTabIndexExtensionConfig>, unknown>

Defined in: packages/lexical-a11y/src/index.ts:715

Platform-independent extension that wires the WAI-ARIA roving-tabindex pattern on a container. Hosts using @lexical/extension supply the container via the config signal; the React adapter is useLexicalRovingTabIndex from @lexical/react.

Functions​

registerAriaLiveRegion()​

registerAriaLiveRegion(options?): AriaLiveRegionHandle

Defined in: packages/lexical-a11y/src/index.ts:83

Mounts a visually hidden aria-live region as a child of owner (default document.body) and returns a handle that announces messages and disposes the region when called.

Framework-agnostic — call from React via useLexicalAriaLiveRegion, from Svelte via onMount / onDestroy, or imperatively from vanilla JS. WAI-ARIA status message pattern (WCAG 4.1.3).

If neither owner nor document.body is available (e.g. SSR), the returned handle is a no-op.

Parameters​

options?​

AriaLiveRegionOptions = {}

Returns​

AriaLiveRegionHandle

registerEditorModeAnnounce()​

registerEditorModeAnnounce(editor, announce, options?): () => void

Defined in: packages/lexical-a11y/src/index.ts:523

Announces editor mode transitions (editor.setEditable(true|false)) into the supplied announce sink. The aria-readonly attribute on the editor root is already managed by other layers; this helper only contributes the announcement.

Framework-agnostic — pair with registerAriaLiveRegion's announce for a vanilla integration, or use EditorModeAnnounceExtension for @lexical/extension hosts.

Parameters​

editor​

LexicalEditor

announce​

(message) => void

options?​

EditorModeAnnounceOptions = {}

Returns​

() => void

registerFocusManager()​

registerFocusManager(editor, toolbar, options?): () => void

Defined in: packages/lexical-a11y/src/index.ts:407

Implements the editor-to-toolbar focus jump recommended by the WAI-ARIA APG editor menubar pattern: Alt+F10 inside the editor moves focus to the first focusable in toolbar, and Escape inside the toolbar returns focus to the editor.

Wires the navigation only. Selection restoration relies on the editor's own focus handling; the editor's last selection is preserved across the jump so toolbar commands act on the same range.

Framework-agnostic — React consumers should use useLexicalFocusManager from @lexical/react.

Parameters​

editor​

LexicalEditor

toolbar​

HTMLElement

options?​

FocusManagerOptions = {}

Returns​

() => void

registerFocusTrap()​

registerFocusTrap(container, options?): () => void

Defined in: packages/lexical-a11y/src/index.ts:177

Traps Tab / Shift+Tab focus inside container and restores focus to the previously-focused element when the returned dispose runs. Intended for modal dialogs and other transient overlays.

While active, any focus that lands outside the container is pulled back inside via a document-level focusin listener. This recovers from Safari's default Tab routing through the browser chrome, but it also means descendants that mount into a portal outside container (autocomplete panels, tooltips, toasts that auto-focus themselves) will be yanked back as soon as they take focus. Portal them inside container, or skip this helper for those dialogs. The pull-back always lands on the first focusable descendant (or the container as a fallback) — initialFocus only applies to the activation-time landing, not to subsequent escape recoveries. Only one trap should be mounted at a time — two active traps install competing document-level focusin listeners and will fight over focus.

Escape is not intercepted — the owner handles close-key behavior.

Framework-agnostic — React consumers should use useLexicalFocusTrap from @lexical/react.

Parameters​

container​

HTMLElement

options?​

FocusTrapOptions = {}

Returns​

() => void

registerHistoryAnnounce()​

registerHistoryAnnounce(editor, announce, options?): () => void

Defined in: packages/lexical-a11y/src/index.ts:477

Announces undo / redo into the supplied announce sink so screen readers pick up history navigation. The announcement fires at COMMAND_PRIORITY_LOW so the history extension's own handler runs first and is unaffected; the handler returns false to keep the command chain intact.

Framework-agnostic — pair with registerAriaLiveRegion's announce for a vanilla integration, or use HistoryAnnounceExtension for @lexical/extension hosts.

Parameters​

editor​

LexicalEditor

announce​

(message) => void

options?​

HistoryAnnounceOptions = {}

Returns​

() => void

registerRovingTabIndex()​

registerRovingTabIndex(container, options?): () => void

Defined in: packages/lexical-a11y/src/index.ts:295

Implements the WAI-ARIA roving-tabindex pattern on container. One item carries tabindex="0" at a time; the rest are -1. Arrow keys move focus inside the group; Home / End jump to the ends. Tab leaves the group as a unit, matching the toolbar / menubar pattern.

Items are queried lazily on every interaction so additions or removals during the lifetime of the group are picked up without extra wiring.

Framework-agnostic — React consumers should use useLexicalRovingTabIndex from @lexical/react.

Parameters​

container​

HTMLElement

options?​

RovingTabIndexOptions = {}

Returns​

() => void