Modal

Structure

The Modal renders its dialog container as an HTML <div> with the dialog ARIA role to communicate its purpose to assistive technology. The Modal is rendered inside a portal so it sits outside the main document flow, preventing interference with page layout.

The Modal uses Floating UI for focus management, dismissal, and role assignment. Floating UI's FloatingFocusManager creates a focus trap that keeps keyboard focus within the dialog while it is open. The useRole hook assigns the dialog role, the useDismiss hook handles Escape key dismissal, and FloatingOverlay locks background scroll to prevent interaction with the page behind the modal.

ARIA

table

Element	Attribute	Description
Close button	aria-label="Close"	Set to "Close" to provide an accessible name for the icon-only close button.
Dialog	aria-labelledby	References the modal title element's ID so assistive technology announces the title when the dialog opens.
Dialog	role="dialog"	Identifies the container as a dialog.

Focus trapping

When a Modal opens, focus is trapped solely within the Modal until it's dismissed. This prevents the user from being forced to cycle through all page elements before landing back in the Modal.

The first focusable element within the Modal receives focus first. If necessary, another element may be targeted as the first focusable element with the initialFocusIndex. When the Modal closes, focus returns to its trigger element.

Keyboard

table

Key	Function
Enter/Space	Activates the focused element within the modal, such as a button in the footer or the close button.
Escape	By default, closes the Modal. Can be disabled with the shouldCloseOnEscapePress prop.
Shift+Tab	Moves focus to the previous focusable element within the modal. Wraps from the first focusable element to the last.
Tab	Moves focus to the next focusable element within the Modal. Focus is trapped inside the Modal and wraps from the last focusable element back to the first.