Skip to main content

@lexical/a11y

Interfaces​

AriaLiveRegionExtensionConfig​

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

Properties​

owner​

owner: HTMLElement | null

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

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:564

AriaPoliteness for the mounted region.

AriaLiveRegionHandle​

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

Properties​

announce​

announce: (message) => void

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

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:51

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:24

Properties​

owner?​

optional owner?: HTMLElement

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

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:30

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:581

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:582

EditorModeAnnounceExtensionConfig​

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

Properties​

editable​

editable: string

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

Message announced when the editor becomes editable.

readOnly​

readOnly: string

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

Message announced when the editor becomes read-only.

EditorModeAnnounceOptions​

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

Properties​

editable?​

optional editable?: string

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

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

readOnly?​

optional readOnly?: string

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

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

FocusManagerExtensionConfig​

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

Properties​

toolbar​

toolbar: HTMLElement | null

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

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:777

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:400

Properties​

toolbarItemSelector?​

optional toolbarItemSelector?: string

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

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:682

Properties​

container​

container: HTMLElement | null

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

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:690

FocusTrapInitialFocus for the activation-time landing.

FocusTrapOptions​

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

Properties​

allowOutside?​

optional allowOutside?: (target) => boolean

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

Predicate that exempts an element from the pull-back. When it returns true for event.target, the focusin handler lets focus stay outside the container. Useful for portaled panels (e.g. autocomplete popups) that live outside the trap container yet logically belong to it.

Parameters​
target​

HTMLElement

Returns​

boolean

initialFocus?​

optional initialFocus?: FocusTrapInitialFocus

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

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:619

Properties​

redone​

redone: string

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

Message announced after a redo.

undone​

undone: string

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

Message announced after an undo.

HistoryAnnounceOptions​

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

Properties​

redone?​

optional redone?: string

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

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

undone?​

optional undone?: string

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

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

RovingTabIndexExtensionConfig​

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

Properties​

container​

container: HTMLElement | null

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

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:733

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:728

RovingOrientation for arrow-key navigation.

RovingTabIndexOptions​

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

Properties​

itemSelector?​

optional itemSelector?: string

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

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:283

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:22

FocusTrapInitialFocus​

FocusTrapInitialFocus = "firstFocusable" | "container"

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

RovingOrientation​

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

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

Variables​

AriaLiveRegionExtension​

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

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

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:662

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:786

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:701

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:630

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:742

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:84

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:550

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:423

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:186

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:507

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:307

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