Dialog

Modal dialogs and alerts with focus trapping and accessible keyboard interactions.

Features

• ✅ Focus trap when dialog is open
• ✅ Escape key to close
• ✅ Focus returns to trigger on close
• ✅ Backdrop click to close
• ✅ Accessible ARIA attributes
• ✅ Prevent body scroll when open
• ✅ Support for programmatic control via events
• ✅ Support for nested dialogs

Basic Usage

Dialog Title

This is a basic dialog example. Click outside or press Escape to close.

Confirmation Dialog

Confirm Deletion

Are you sure you want to delete this item? This action cannot be undone.

Programmatic Control

You can control dialogs programmatically using custom events with the name prop.

Programmatic Dialog

This dialog was opened using a custom event.

With Transitions

Animated Dialog

This dialog smoothly fades and scales in.

Full Screen Modal

Full Screen Dialog

This is a full screen modal dialog. Perfect for complex forms, image galleries, or detailed content.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.

Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

Drawer/Flyout Modal

Drawer Menu

This drawer slides in from the right side of the screen.

DashboardProjectsTeamSettings

API Reference

Component Props

Prop	Type	Default	Description
name	string	-	Unique identifier for programmatic control
open	boolean	false	Controlled open state
modal	boolean	true	Enable modal behavior (focus trap, scroll lock)
closeOnInteractOutside	boolean	true	Close when clicking backdrop
closeOnEscape	boolean	true	Close when pressing Escape key
trapFocus	boolean	true	Trap focus within dialog
preventScroll	boolean	true	Prevent body scroll when open
role	'dialog' | 'alertdialog'	'dialog'	ARIA role for the dialog

Parts

Part	Description
x-dialog	Root container element
x-dialog:trigger	Button that opens the dialog
x-dialog:backdrop	Backdrop/overlay element
x-dialog:positioner	Positions the dialog content
x-dialog:content	Dialog content container
x-dialog:title	Dialog title (for aria-labelledby)
x-dialog:description	Dialog description (for aria-describedby)
x-dialog:close-trigger	Close button

Data Attributes

Attribute	Description
data-scope	Always set to dialog
data-part	Identifies the part (root, trigger, backdrop, etc.)
data-state	Current state (open or closed) on root

Events

Dispatched by component:

Event	Detail	Description
open	{ open: true }	Fired when dialog opens
close	{ open: false }	Fired when dialog closes

Listened for (window events):

Event	Detail	Description
modal:open	string (dialog name)	Opens dialog matching the name
modal:close	string (dialog name)	Closes dialog matching the name

Accessibility

Keyboard Interactions

Key	Action
Escape	Closes the dialog
Tab	Moves focus to next focusable element within dialog
Shift + Tab	Moves focus to previous focusable element within dialog

Focus Management

• When opened, focus moves to the first focusable element in the dialog
• Focus is trapped within the dialog while open (in modal mode)
• When closed, focus returns to the trigger button
• Focusable elements include: links, buttons, inputs, selects, textareas, and elements with tabindex >= 0

ARIA Attributes

The dialog automatically includes:

• role="dialog" (or role="alertdialog") on the content
• aria-modal="true" on the content (when modal)
• aria-labelledby pointing to the title
• aria-describedby pointing to the description
• aria-expanded on the trigger
• aria-haspopup="dialog" on the trigger

Tips

• Modal vs Non-modal: Use modal: true for dialogs that require user attention before continuing. Use modal: false for informational dialogs that don't block interaction.
• Alert Dialog: Use role: 'alertdialog' for dialogs that require immediate user response (like confirmations or warnings).
• Programmatic Control: Use the name prop with window events to open/close dialogs from anywhere in your application.
• Transitions: Combine with Alpine's x-transition directives for smooth animations.
• Nested Dialogs: The component supports multiple dialogs with proper focus and scroll management.