Basic
Dialog with trigger and content.
overlaysstable
Modal
Accessible modal dialogs with focus management, dismissal, and compound structure.
Animation
Easing
Options
Usage
Import the component and configure it with the same props used in the playground.
Examples
Common patterns and practical usage examples.
No outside dismissal
Requires an explicit close action.
Fade animation
Uses an alternate transition for modal entry and exit.
Large scrollable content
Uses a larger panel with inside scrolling for long content.
Alert dialog
Uses alert dialog semantics for destructive confirmation.
API
Props available for the React Modal.
Modal
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | - | Modal trigger, overlay, content, and compound children. |
modal | boolean | true | Uses modal interaction semantics while open. |
preventScroll | boolean | true | Prevents document scrolling while the modal is open. |
trapFocus | boolean | true | Keeps keyboard focus inside the modal while open. |
initialFocus | RefObject< | - | Element that should receive focus when the modal opens. |
finalFocus | RefObject< | - | Element that should receive focus when the modal closes. |
onOpenAutoFocus | ( | - | Called before focus moves into the modal after opening. |
onCloseAutoFocus | ( | - | Called before focus is restored after closing. |
onEscapeKeyDown | ( | - | Called when Escape is pressed while the modal is open. |
onPointerDownOutside | ( | - | Called when a pointer down occurs outside modal content. |
onInteractOutside | ( | - | Called when an interaction occurs outside modal content. |
role | 'dialog' | 'dialog' | ARIA role applied to the modal content. |
className | string | - | Class name applied to the modal root. |
open | boolean | - | Controlled open state. |
defaultOpen | boolean | - | Initial open state for uncontrolled usage. |
onOpenChange | ( | - | Called when the open state changes. |
closeOnOutsidePress | boolean | true | Closes the modal when the overlay is pressed. |
closeOnEscape | boolean | true | Closes the modal when the Escape key is pressed. |
animation | 'scale' | 'scale' | Animation style used when the modal opens and closes. |
duration | ModalAnimationDuration | - | Animation duration in milliseconds, or separate open and close durations. |
easing | 'standard' | - | Animation easing curve. |
restoreFocus | boolean | true | Restores focus to the previously focused element after closing when supported. |
Modal.Trigger
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | - | Trigger content. |
asChild | boolean | - | Composes trigger behavior onto a single child element. |
disabled | boolean | - | Disables trigger interaction. |
className | string | - | Class name applied to the trigger element. |
Modal.Overlay
| Prop | Type | Default | Description |
|---|---|---|---|
animated | boolean | - | Enables enter and exit animation for the overlay. |
className | string | - | Class name applied to the overlay element. |
forceMount | boolean | - | Keeps the overlay mounted even when the modal is closed. |
Modal.Content
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | - | Modal panel content. |
size | 'sm' | - | Preset modal panel width. |
placement | 'center' | - | Vertical placement for the modal panel. |
scrollBehavior | 'inside' | - | Controls whether scrolling happens inside the panel or outside it. |
animated | boolean | - | Enables enter and exit animation for the panel. |
forceMount | boolean | - | Keeps content mounted even when the modal is closed. |
ariaLabel | string | - | Accessible label applied directly to the modal panel. |
ariaLabelledBy | string | - | Id of the element that labels the modal panel. |
ariaDescribedBy | string | - | Id of the element that describes the modal panel. |
className | string | - | Class name applied to the modal panel. |
style | CSSProperties | - | Inline style applied to the modal panel. |
Modal.Header
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | - | Header content, typically title and description. |
className | string | - | Class name applied to the header element. |
Modal.Body
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | - | Main modal body content. |
className | string | - | Class name applied to the body element. |
Modal.Footer
| Prop | Type | Default | Description |
|---|---|---|---|
childrenRequired | ReactNode | - | Footer actions or custom footer content. |
className | string | - | Class name applied to the footer element. |
Modal.Close
| Prop | Type | Default | Description |
|---|---|---|---|
asChild | boolean | - | Composes close behavior onto a single child element. |
children | ReactElement< | - | Custom close button element. |
aria-label | string | - | Accessible name for the close button. |
className | string | - | Class name applied to the close button. |
Accessibility
Guidance for accessible usage and interaction.
Focus management
Trap focus while open and restore focus to the trigger when the modal closes.
trapFocusrestoreFocusinitialFocusfinalFocusDialog labelling
Use title and description content so assistive technology can announce the dialog purpose.
rolechildrenDismissal
Choose outside press and Escape dismissal behavior based on task criticality.
closeOnOutsidePresscloseOnEscapeDestructive confirmations
Use alert dialog semantics only for urgent decisions that require immediate attention.
roleScrollable content
Keep title, description, and final actions reachable when modal content is long.
scrollBehaviorsize