Dialog Primitive
Headless, unstyled dialog primitive with full accessibility support.
AsChild Pattern
Use AsChild to compose triggers with your own styled elements.
Without AsChild
DialogTrigger renders its own button element.
With AsChild
Button receives click behavior via TriggerContext.
Basic Headless Primitive
The primitive provides behavior and accessibility without styling.
Controlled State
Control the dialog's open state from your component code.
Modal Behavior
By default, dialogs are modal. Clicking overlay or pressing Escape closes the dialog.
Accessibility Features
Built-in accessibility features following WAI-ARIA design patterns.
ARIA Attributes
- ✓
role="dialog"for screen readers - ✓
aria-labelledbylinks title to dialog - ✓
aria-describedbylinks description to dialog - ✓ Automatic focus trap and restoration
- ✓ Body scroll lock when dialog is open
- ✓ Portal rendering for proper z-index stacking
Keyboard Shortcuts
Navigate and interact with dialogs using keyboard.
API Reference
Component properties and parameters.
Dialog
Open
Type: bool?
Controls whether the dialog is open (controlled mode).
OpenChanged
Type: EventCallback<bool>
Callback invoked when the open state changes.
DefaultOpen
Type: bool
Default: false
Initial open state (uncontrolled mode).
Modal
Type: bool
Default: true
Whether the dialog is modal (blocks interaction with rest of page).
DialogTrigger
ChildContent
Type: RenderFragment?
Button content that opens the dialog.
DialogPortal
ChildContent
Type: RenderFragment?
Content rendered at document body level for proper stacking.
DialogOverlay
CloseOnClick
Type: bool
Default: true
Whether clicking the overlay closes the dialog.
DialogContent
CloseOnEscape
Type: bool
Default: true
Whether pressing Escape closes the dialog.
TrapFocus
Type: bool
Default: true
Whether to trap focus inside the dialog.
LockScroll
Type: bool
Default: true
Whether to prevent body scroll when dialog is open.
DialogTitle / DialogDescription / DialogClose
ChildContent
Type: RenderFragment?
Content rendered inside the component.
When to Use Primitives
Choose between primitives and styled components based on your needs.
Use Dialog Primitive
- ✓ Building a custom design system
- ✓ Need complete control over styling
- ✓ Want to apply your own CSS framework
- ✓ Creating unique visual designs
Use Styled Component
- ● Want shadcn/ui design out of the box
- ● Need quick implementation
- ● Like the default styling
- ● Prefer convention over configuration