Components

Dialog

Dialogs present focused content or actions in a modal overlay above the main page.

Stable

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

Inherits props fromBase UI Dialog Root

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

Trigger

Inherits props fromBase UI Dialog Trigger

Name	Type	Description
`children`	`ReactNode`	Opens the dialog when activated. Passed as a single button element, not via a render prop.

Close

Inherits props fromBase UI Dialog Close

Dismisses the dialog when activated.

Name	Type	Description
`children`	`ReactNode`	The element that closes the dialog. Passed as a single button element, not via a render prop.

Inherits props fromBase UI Dialog Popup

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

Name	Type	Description
`children`	`ReactNode`	The content of the dialog, typically a header, body, and footer.
`container`	`HTMLElementRefObject<HTMLElement>`	Use this instead of z-index to specify another parent element to render the dialog portal into. Default is the document body.

Header

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

Name	Type	Description
`children`	`ReactNode`	The header content, typically a title and a close button.

Body

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

Name	Type	Description
`children`	`ReactNode`	The main content of the dialog.

Footer

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

Name	Type	Description
`children`	`ReactNode`	The footer content, typically action buttons.

Title

Inherits props fromBase UI Dialog Title

Renders an <h2> element that labels the dialog.

Name	Type	Description
`children`	`ReactNode`	A heading that labels the dialog.

Description

Inherits props fromBase UI Dialog Description

A visually hidden element available and recommended to use.

Name	Type	Description
`children`	`ReactNode`	A description that provides additional context for the dialog.

Anatomy

Use the anatomy examples to keep dialogs structured around a clear title, optional controls in the header, a scrollable content area when needed, and a footer for actions.

Properties

Header Close Button

A dialog header can include an optional close button. Use it only when it does not compete with a footer action pattern that already provides a clear way out.

Header Button(s)

Header buttons are useful for tasks such as upload or other context-specific actions that belong next to the title.

Header Content

Use header content for sticky filters or sorting options when those controls need to stay visible while the dialog body scrolls.

Scrolling

Enable scrolling when the dialog content exceeds the available viewport. Keep the top-level structure stable so the title and actions remain easy to find.

Footer

The footer holds the main dialog actions and should remain visible when the content area scrolls.

Footer Content

Use footer content for action state or supporting metadata when that information helps users complete the task.

Behaviour

Breakpoints

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

Best Practices

More modals = More problems

The best modal is a new page. Modal dialogs are often misused. All too often they contain too much content that would be better off as a new page. This improves performance and doesn’t break the back button like a dialog often does.

When to use a dialog?

Use dialogs for focused tasks that require immediate action. Keep the purpose clear, limit the amount of content, and avoid turning a dialog into a long multi-step flow.

Do not put a modal on top of a modal. If the task gets more complex, consider a multistep flow instead.

Closing a dialog

Include at least one close option. Use a clear Close or Cancel action, and avoid duplicating close controls in both the header and footer unless the pattern explicitly requires it.

Avoid duplicated close actions

Avoid placing duplicate close controls in both header and footer when one clear close option is already present.

Content Guidelines

Header/Title

Use Title Case for dialog titles.

Content

Keep dialog content concise and relevant. Follow the same writing standards you already use for field labels, inline error messages, buttons, and other content inside the modal.