Astryx Design System

Dialog@astryxdesign/core v0.0.15 · Dialog

Usage

Dialog displays a modal overlay that blocks interaction with the page until the user responds. Use it for delete confirmations, edit forms, terms acceptance, or any decision that should not be skipped.

For cases where you want to show a dialog without managing open state, use the useImperativeDialog hook: call dialog.show(content) and render dialog.element in your tree.

ts
import {Dialog} from '@astryxdesign/core/Dialog'

Best practices

Guidance	Practices
Do	Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.
Do	Include a clear title in the header so users immediately understand what the dialog is asking.
Do	Use purpose="form" for dialogs with inputs so the user can't accidentally lose data by clicking the backdrop.
Do	Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.
Don't	Use a dialog for simple messages that could be shown inline or as a toast notification.
Don't	Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.
Don't	Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.

Examples

Common configurations, variations, and states.

Dialog — Confirmation

Asks the user to confirm a destructive action before it happens. Use before deleting projects, removing team members, revoking API keys, or any irreversible operation.

Dialog — Form

Collects user input without navigating away from the page. Uses purpose="form" so clicking the backdrop won't close it. Use for editing profiles, creating items, or updating settings inline.

Dialog — Fullscreen

Takes over the entire viewport for content that needs maximum space. Use for documentation viewers, rich text editors, multi-step wizards, or media previews where the standard dialog width is too narrow.

Dialog — Scrollable

Constrains the dialog height and scrolls the body when content overflows. Use for terms and conditions, license agreements, changelogs, or any long-form content the user needs to review before accepting.

Dialog — Required

Cannot be dismissed by Escape or backdrop click; the user must explicitly choose an action. Uses purpose="required". Use for ownership transfers, legal acknowledgements, or critical decisions where skipping is not an option.

Usage

For cases where you want to show a dialog without managing open state, use the useImperativeDialog hook: call dialog.show(content) and render dialog.element in your tree.

import {Dialog} from '@astryxdesign/core/Dialog'

Best practices

Guidance	Practices
Do	Choose the right purpose: info for dismissable content, form to prevent accidental backdrop dismissal, required when the user must respond.
Do	Include a clear title in the header so users immediately understand what the dialog is asking.
Do	Use purpose="form" for dialogs with inputs so the user can't accidentally lose data by clicking the backdrop.
Do	Keep dialogs focused on a single task; if the content grows beyond what fits, consider a full page instead.
Don't	Use a dialog for simple messages that could be shown inline or as a toast notification.
Don't	Nest dialogs inside other dialogs; restructure the flow into steps within a single dialog instead.
Don't	Use the fullscreen variant for simple confirmations; it is meant for complex content like editors or long forms.