Dialog

When to use

Dialog is for a short, focused task or decision that people finish without leaving the page: editing an item, confirming a setting, signing in again when a session ends.

When not to use

• To confirm an action that cannot be undone: Use AlertDialog.
• To show details or filters while the list stays visible: Use a Drawer; the page context stays in view.
• For long, multi-step tasks: Open a separate page.
• To inform: An inline alert or a short notification (Toast) is enough; a dialog stops people.

Anatomy

Open dialog

LightDark

Copy code

import { Button, Dialog } from '@bigbang/ui';

export default function Default() {
  return (
    <Dialog
      trigger={<Button>Open dialog</Button>}
      title="Dialog title"
      description="Dialog description goes here."
      footer={
        <>
          <Dialog.Close>
            <Button variant="secondary">Cancel</Button>
          </Dialog.Close>
          <Dialog.Close>
            <Button>Save</Button>
          </Dialog.Close>
        </>
      }
    >
      Body content goes here. Keep the dialog to one task.
    </Dialog>
  );
}

1. Backdrop: Lightly dims and blurs the page and closes the dialog when pressed.
2. Panel: Raised surface, 16 px corners, 1 px hairline.
3. Title and description: Name the dialog and explain its purpose.
4. Body: Scrolls on its own when it is long.
5. Actions: On a band at the bottom, aligned to the end, the most important one last; below 640 px stacked, the most important one on top.
6. Close button: Top end corner; absent for a forced decision.

Behaviour

• Opens from its trigger or through the controlled open prop.
• On open, focus moves to the first focusable element in the body, otherwise to the actions; initialFocus changes this.
• Focus cycles inside the dialog; the page behind is inert and does not scroll.
• Escape, a press on the backdrop, the close button or Dialog.Close close it; focus returns to the trigger.
• With dismissible={false} only an action closes it.
• A body taller than the dialog scrolls on its own and joins the tab order so it can be scrolled with the keyboard.
• Below 640 px a dismissible dialog becomes a bottom sheet and its actions stack at full width.

Guidelines

• Keep one task per dialog.
• Write the title as a short phrase that names the task.
• Name the primary action with a verb and place it last.
• Avoid opening a dialog from a dialog.
• Ask for confirmation when closing would lose unsaved changes.

Content

• Titles use sentence case with no full stop.
• The description is one or two sentences.
• The close button’s name comes from the ui.dialog.close library string.

Turkish	English
Pencere başlığı	Dialog title
Vazgeç	Cancel
Kaydet	Save

Glass

Under a Provider material="glass", the dialog turns glass with the higher-contrast tint, and the action band drops its fill. material="solid" keeps it solid. Glass suits short confirmations. Set material="solid" for long text, a form with more than three fields or a consent block.

Related components

• AlertDialog: A one-question confirmation.
• Button: Dialog actions.
• Tooltip: A short hint that does not hold focus.