Dialog

Anatomy

import {Dialog} from '@staffbase/design';

<Dialog.Root>
  <Dialog.Trigger />
  <Dialog.Popup>
    <Dialog.Header>
      <Dialog.Title />
      <Dialog.Close />
    </Dialog.Header>
    <Dialog.Body>
      <Dialog.Description />
    </Dialog.Body>
    <Dialog.Footer />
  </Dialog.Popup>
</Dialog.Root>

API reference

Root

Groups all parts of the dialog and manages its open state.

Trigger

Close

Dismisses the dialog when activated.

Popup

Renders the modal surface and its backdrop, portalled out of the DOM flow.

Header

Renders a <div> that lays out the title and close button.

Body

Renders a <div> for the main content of the dialog.

Footer

Renders a <div> that lays out the dialog’s actions.

Title

Renders an <h2> element that labels the dialog.

Description

Renders a <p> element that describes the dialog, linked to it via aria-describedby. Visible by default; you can visually hide it with a utility class if needed.

When to use

• For a focused task that needs immediate attention or completion, such as confirming an action or filling in a short form.
• When the user must finish or explicitly dismiss the task before returning to the page.
• When the content is small and self-contained enough to fit a single step.

When not to use

• Don’t put large or complex content in a dialog — use a new page instead. The best modal is a new page: it performs better and doesn’t break the back button.
• Don’t open a dialog on top of another dialog — use a multi-step flow or a new page instead.
• Don’t use a Dialog for confirming a critical or destructive action — use AlertDialog instead.
• Don’t use a Dialog for lightweight contextual content anchored to its trigger — use Popover instead.

How to use

Structure

• Structure every dialog around a clear title in the header, the main content in the body, and actions in the footer.
• Keep the top-level structure stable so the title and actions remain easy to find, even when content scrolls.

Header

• Use header buttons for context-specific actions that belong next to the title, such as upload.

• Use header content for sticky filters or sorting options that need to stay visible while the dialog body scrolls.

Footer

• The footer holds the main dialog actions and remains visible when the content area scrolls.
• Use footer content for action state or supporting metadata when that information helps users complete the task.

Scrolling

• Enable scrolling when the dialog content exceeds the available viewport.
• Only the body scrolls — the header and footer stay in place so the title and actions remain visible.

Layout & responsive behavior

• From 0 to 480px, the dialog is full width and full height with no border radius.
• From 480px and up, it uses 88% width with a maximum width of 800px, and a height that wraps the content with a maximum height of 88%.

Closing

• It’s recommended to provide both a header close button and a footer Cancel action so users always have an obvious way out. Undoing an action is as important as doing it. The X provides a familiar way to dismiss the modal, while Cancel is a clear, labelled action that communicates what will happen.

Accessibility

• Always provide a Dialog.Title — it labels the dialog for assistive technology.
• Include a Dialog.Description to give screen reader users additional context; it can be visually hidden.
• Give an icon-only header close button an accessible label, such as aria-label="Close".
• Focus is trapped inside the dialog while it is open and returns to the trigger when it closes.

Content & UX copy

• Use Title Case for dialog titles.
• Keep dialog content concise and relevant — a dialog is a single focused task, not a long read.
• Follow the same writing standards used for field labels, inline error messages, and buttons elsewhere in the product.