- Docs
- Accessibility and focus
Accessibility and focus
Name dialogs, choose modal behavior, preserve focus and scroll ownership, and keep forms and drag gestures accessible.
@samline/drawer supplies dialog semantics, focus management, modal isolation, keyboard dismissal, and accessible built-in controls. The application still owns meaningful labels, content order, visible focus styles, and validation or status messages inside the panel.
Give every drawer a useful name
Prefer a visible title when the interface has a heading:
createDrawer({
id: 'filters',
title: 'Filter products',
description: 'Choose one or more filters, then apply them.',
content: buildFilterForm(),
})
The title slot becomes the aria-labelledby target. Descriptions are visually hidden by default and become the aria-describedby target. Set descriptionVisuallyHidden: false when the description should also be visible.
For a drawer without a visible heading, use ariaLabel:
createDrawer({ id: 'quick-actions', ariaLabel: 'Quick actions' })
If neither title nor label is supplied, the id is used as a fallback label. That prevents an unnamed dialog but is rarely good user-facing copy.
Use ariaLabelledBy or ariaDescribedBy when the matching nodes live in custom content. You are responsible for keeping those ids present whenever the dialog is mounted.
Modal focus ownership
With the default modal: true, the drawer:
- mounts an overlay;
- moves focus to the dialog container by default, or its first visible control with
autoFocus: true; - traps Tab and Shift+Tab inside, skipping controls with a negative
tabindex, disabled controls and hidden or inert subtrees; - isolates background branches with
inertandaria-hidden; - locks page scroll;
- restores focus when it closes. A structural
update()while open rebuilds the panel without moving focus to the page behind it.
modal: false omits those modal effects and, by default, the overlay. Set overlay: true when a modeless drawer needs a local backdrop and overlay-click dismissal; content outside its container remains interactive.
Set autoFocus: true to focus the first visible focusable control. Focus a specific control from application code after opening when the flow needs another starting point. With the default autoFocus: false, focus still moves to the dialog container; this option does not disable modal focus ownership.
Dismissal is a product decision
dismissible: true enables Escape, overlay clicks, drag-to-close, and dismissal from the last handle state. An overlay click dismisses only when the press both starts and ends on the overlay, so a text selection that ends outside the panel keeps it open. Escape is ignored while an input method editor is composing text. The built-in close button and programmatic methods can still close a drawer when dismissible: false.
For blocking flows, provide an explicit labeled action rather than relying on gesture dismissal:
createDrawer({
id: 'terms',
title: 'Terms of service',
dismissible: false,
closeButton: { ariaLabel: 'Close terms' },
content: buildTerms(),
})
The built-in handle is a named button only when it can act: with snap points and without preventCycle, clicking or pressing Enter cycles heights. Set handleAriaLabel to describe that action in context. Without snap points, or with preventCycle, the handle stays a pointer drag affordance with tabindex="-1" and aria-hidden="true", so keyboard and screen-reader users do not meet a button that does nothing.
Interactive content and drag
Inputs, buttons, links, and editable content participate in the drawer’s gesture policy. Add data-drawer-no-drag around interactions whose horizontal or vertical pointer movement must remain entirely theirs:
<div class="map" data-drawer-no-drag aria-label="Store map"></div>
The mobile viewport pipeline is enabled by default through repositionInputs. It responds while an input is focused and the visual viewport changes. fixed: true also adjusts calculated height; it is not required for basic keyboard repositioning.
Accessibility checklist
- Use a concise visible
titleor meaningfulariaLabel. - Add
descriptiononly when it adds context beyond the title. - Keep visible focus indicators in your theme.
- Verify Tab and Shift+Tab wrap inside modal drawers.
- Verify Escape and the close button match the intended dismissal policy.
- Verify focus returns to the trigger after close.
- Test controls inside scrollable and
data-drawer-no-dragregions with mouse, touch, and keyboard. - Respect reduced-motion preferences. The package stylesheet removes drawer, overlay and scaled-wrapper animation under
prefers-reduced-motion: reduce; apply the same preference to any motion your own overrides add. - Destroy drawers when their owning view unmounts so hidden hosts and triggers do not remain in the accessibility tree.