Dialog | Surflane

Preview

Local preview. It doesn't affect real accounts, environments, or run data.

Compare the same example at each size and density. Switching keeps input values and selection state. Size guidance and comparisons

Usage

Run a task that needs the user's full attention, such as editing a resource or confirming a plan. Include a Title and a Description; every dialog shows the close (X) button, and Footer holds the task's actions.
To read the details of an item from a list or a card grid, such as a session or a deployment, open a Sheet beside them instead, so the list stays in view. A long history with tabs belongs on a page of its own.

Don't repeatedly block the flow for simple notices. Use a Toast instead.
Don't confirm data loss in a Dialog. Use a separate AlertDialog.
Don't add a Close button to the footer of a dialog that has no task: the close (X) button already does it. A footer holds actions, such as Save and Cancel.

Size: SizeProvider size="small" resizes the whole composition, including portals. The default size is Default. Size guidance and comparisons

Anatomy

Root → Trigger → Content → Header(Title / Description / X) + Body + Footer

Keyboard and accessibility

Tab keeps focus inside the dialog. Escape or the close button closes it. A nested Select closes first, then the parent Dialog.

Give each control a name that describes its purpose. Connect error messages to their controls, and signal state with more than color. Automated checks don't replace manual keyboard and assistive technology testing.

Example code

Shared components take their styles from design tokens. Each example sets its own composition and accessibility attributes. The calling screen defines callbacks, refs, and product data.

import { Dialog, Button } from '@surflane/ui'

<Dialog.Root>
  <Dialog.Trigger render={<Button />}>Open plan</Dialog.Trigger>
  <Dialog.Content closeLabel='Close plan'>
    <Dialog.Header>
      <Dialog.Title>Deployment plan</Dialog.Title>
      <Dialog.Description>Preview only.</Dialog.Description>
    </Dialog.Header>
    <Dialog.Body>Plan details</Dialog.Body>
    <Dialog.Footer>
      <Dialog.Close render={<Button />}>Done</Dialog.Close>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog.Root>

Key API

Dialog — common wrapper props
Prop	Contract	Default
`Content.closeLabel`	names the close (X) button, which every dialog shows	Close dialog
`Content.closeDisabled`	disables the close button, such as while a save runs	false
`Content.focusBoundaryLabel`	names the focus guards at the edges, which screen readers reach past the last control	Continue dialog navigation
`Content.initialFocus`	ref / focus callback (Base UI)	Base UI default
`Content.size`	small \| default \| large: 420 / 640 / 840px wide, and density	default width, surrounding density
`--surf-dialog-width`	custom property: a width that keeps the surrounding density	Content.size
`Root.open / onOpenChange`	controlled dialog state	—

The table lists the common wrapper's main props. See the package type declarations for the full types.