Skip to main content

Dialog

Present a labeled modal task with structured content and dismissal.

Props
Slots

Anatomy#

Dialog [component; no DOM]
├── Dialog.Trigger [part; slot=trigger]
├── Dialog.Close [part]
└── overlay [slot]
    └── Dialog.Content [part; slot=content]
        ├── Dialog.Header [part; slot=header]
        │   ├── Dialog.Title [part; slot=title]
        │   └── Dialog.Description [part; slot=description]
        ├── contentClose [slot]
        ├── Dialog.Body [part; slot=body]
        └── Dialog.Footer [part; slot=footer]

Content is portaled and renders inside the overlay element. With overlay={false}, that element is an unstyled wrapper without the overlay slot.

Usage#

Use Dialog for a labeled modal task with title, description, body, and footer. Use BaseDialog when you compose backdrop and content yourself. Use Sheet or Drawer for a panel from a viewport edge. Use Popover for anchored interactive content that should not take over the page. Use Tooltip for a brief non-interactive hint. Use DropdownMenu or ContextMenu for an action list. Use Alert Dialog for confirm, info, warning, error, and success prompts opened from an event handler.

The trigger and content share disclosure state through the root.

import { Button, Dialog } from 'moraine'

export function Example() {
  return (
    <Dialog>
      <Dialog.Trigger as={Button}>Open</Dialog.Trigger>
      <Dialog.Content title="Settings">
        <Dialog.Body>Preferences</Dialog.Body>
        <Dialog.Footer>
          <Dialog.Close as={Button}>Done</Dialog.Close>
        </Dialog.Footer>
      </Dialog.Content>
    </Dialog>
  )
}

Content composition#

Use Content title and description for simple cases:

<Dialog>
  <Dialog.Content title="Settings" description="Update your account.">
    <Dialog.Body>...</Dialog.Body>
    <Dialog.Footer>...</Dialog.Footer>
  </Dialog.Content>
</Dialog>

For a custom header layout, compose the anatomy parts:

<Dialog.Content>
  <Dialog.Header>
    <Dialog.Title>Settings</Dialog.Title>
    <Dialog.Description>Update your account.</Dialog.Description>
  </Dialog.Header>
  <Dialog.Body>...</Dialog.Body>
  <Dialog.Footer>...</Dialog.Footer>
</Dialog.Content>

An explicit Dialog.Header replaces the header generated by Content’s title and description. Dialog.Title and Dialog.Description connect their IDs to the surface’s accessible name and description. Without a visible title, set aria-label or aria-labelledby on Content.

Dialog.Close is an explicit close control you can place inside the root; it is separate from Content’s automatic corner close button. Set root closable={false} to hide the corner button, or closeIcon to replace its icon. Its accessible label comes from the close message; override it with root translations. See Localization. Root transition={false} turns off the enter and exit animations, so content and overlay unmount as soon as the dialog closes.

Focus and outside interaction#

modal defaults to true: focus stays inside the surface, outside content is hidden from assistive technology, and native outside pointer actions are prevented. Closing restores focus to the trigger. Use initialFocus to choose the element that receives focus on open, or false to skip the move, and finalFocus to choose where focus returns. Both apply only while modal is true.

Setting modal={false} allows focus to leave the surface, but does not disable Escape or outside dismissal. closeOnOverlayClick and closeOnEscape control those close requests. Both default to true. Scroll locking is independent: preventScroll defaults to true. For interaction with the background page, also set preventScroll={false} and overlay={false}.

Styling and portal placement#

Apply class and object style directly to each rendered part. Root classes and styles set slot defaults for every part: trigger, overlay, content, header, title, description, contentClose, body, and footer. See Customization for precedence.

Set root mount to place Content in a chosen container. This also works for controlled surfaces without a Trigger.

Nested overlays#

Nested roots keep dismissal and focus restoration local to the active layer. Escape closes the topmost dialog or popover, then returns focus to its trigger inside the parent dialog.

<Dialog>
  <Dialog.Content title="Workspace settings">
    <Popover>
      <Popover.Trigger as={Button}>Help</Popover.Trigger>
      <Popover.Content aria-label="Settings help">Workspace-only changes.</Popover.Content>
    </Popover>
    <Dialog>
      <Dialog.Trigger as={Button}>Confirm</Dialog.Trigger>
      <Dialog.Content title="Confirm changes">...</Dialog.Content>
    </Dialog>
  </Dialog.Content>
</Dialog>

State and dismissal#

Use controlled open with onOpenChange when the surrounding flow owns visibility. closeOnOverlayClick={false} blocks an outside pointer press, and closeOnEscape={false} blocks Escape. Both report the attempt through onClosePrevented. Provide a clear explicit close path when either one is blocked.

<Dialog
  open={open()}
  onOpenChange={setOpen}
  closeOnOverlayClick={false}
  closeOnEscape={false}
  onClosePrevented={onBlocked}
>
  <Dialog.Content title="Unsaved changes">
    <Dialog.Footer>
      <Button onClick={() => setOpen(false)}>Discard</Button>
      <Button onClick={() => setOpen(false)}>Save</Button>
    </Dialog.Footer>
  </Dialog.Content>
</Dialog>

Structure and lifecycle#

Use root scrollable for long content or fullscreen for a full-viewport task. onExitComplete runs after the overlay and content finish their exit animations.

<Dialog scrollable>
  <Dialog.Content title="Release notes">...</Dialog.Content>
</Dialog>
<Dialog fullscreen onExitComplete={() => setStatus('Exit animation completed')}>
  <Dialog.Content title="Release notes">...</Dialog.Content>
</Dialog>

Keyboard interaction#

Key Description
Esc Requests dismissal when closeOnEscape is not false.
⇥ Moves focus forward through focusable controls inside the dialog.
Shift + Tab Moves focus backward through focusable controls inside the dialog.

Examples#

Delete a saved filter#

Keep the filter visible until the user confirms. Cancel and backdrop dismissal leave it intact.

import { Button, Dialog } from 'moraine'
import { createSignal, Show } from 'solid-js'

export function DeleteConfirmation() {
  const [exists, setExists] = createSignal(true)
  const [open, setOpen] = createSignal(false)

  return (
    <div class="flex gap-3 items-center">
      <Show when={exists()} fallback={<p class="text-sm">Saved filter removed.</p>}>
        <span class="text-sm">Saved filter: Assigned to me</span>
        <Dialog open={open()} onOpenChange={setOpen}>
          <Dialog.Trigger as={Button} variant="outline" size="sm">
            Delete
          </Dialog.Trigger>
          <Dialog.Content
            title="Delete saved filter?"
            description="Assigned to me will be removed from your saved filters."
          >
            <Dialog.Body>
              <p class="text-sm">You can create another filter later.</p>
            </Dialog.Body>
            <Dialog.Footer>
              <div class="flex gap-2 w-full justify-end">
                <Dialog.Close as={Button} variant="outline">
                  Cancel
                </Dialog.Close>
                <Button
                  variant="solid"
                  tone="danger"
                  onClick={() => {
                    setExists(false)
                    setOpen(false)
                  }}
                >
                  Delete filter
                </Button>
              </div>
            </Dialog.Footer>
          </Dialog.Content>
        </Dialog>
      </Show>
    </div>
  )
}

Confirm workspace changes from settings#

Nest a confirmation dialog and a help popover inside a parent dialog. Escape closes the topmost layer and restores focus to its trigger.

import { Button, Dialog, Popover } from 'moraine'

export function NestedOverlays() {
  return (
    <Dialog>
      <Dialog.Trigger as={Button} variant="outline">
        Open nested overlays
      </Dialog.Trigger>
      <Dialog.Content
        title="Workspace settings"
        description="Review help before confirming your workspace changes."
      >
        <Dialog.Footer class="flex-wrap gap-3">
          <Popover>
            <Popover.Trigger as={Button} variant="outline">
              View settings help
            </Popover.Trigger>
            <Popover.Content aria-label="Settings help" class="p-3">
              Changes apply to this workspace only.
            </Popover.Content>
          </Popover>
          <Dialog>
            <Dialog.Trigger as={Button}>Confirm workspace changes</Dialog.Trigger>
            <Dialog.Content
              title="Confirm changes"
              description="Escape closes this confirmation before closing workspace settings."
            >
              <Dialog.Footer>
                <Dialog.Close
                  as={Button}
                  variant="outline"
                  class="px-3 py-1.5 h-auto w-auto static"
                >
                  Return to settings
                </Dialog.Close>
              </Dialog.Footer>
            </Dialog.Content>
          </Dialog>
        </Dialog.Footer>
      </Dialog.Content>
    </Dialog>
  )
}

Save unsaved configuration#

Own visibility from the page. Toggle closeOnOverlayClick and closeOnEscape together to block outside clicks and Escape. onClosePrevented counts blocked attempts until Save or Discard.

import { Badge, Button, Dialog } from 'moraine'
import { createSignal, Show } from 'solid-js'

export function StateDismissal() {
  const [open, setOpen] = createSignal(false)
  const [allowDismiss, setAllowDismiss] = createSignal(false)
  const [preventedAttempts, setPreventedAttempts] = createSignal(0)

  return (
    <div class="flex flex-wrap gap-4 items-center">
      <Button onClick={() => setOpen(true)}>
        Open {allowDismiss() ? 'Dismissible' : 'Non-Dismissible'} Dialog
      </Button>

      <Button
        variant="outline"
        onClick={() => {
          setAllowDismiss((prev) => !prev)
          setPreventedAttempts(0)
        }}
      >
        Mode: {allowDismiss() ? 'Overlay and Escape' : 'Strict (Buttons Only)'}
      </Button>

      <Dialog
        open={open()}
        onOpenChange={setOpen}
        closeOnOverlayClick={allowDismiss()}
        closeOnEscape={allowDismiss()}
        onClosePrevented={() => setPreventedAttempts((c) => c + 1)}
      >
        <Dialog.Content
          title="Unsaved Configuration Changes"
          description="Explicit confirmation is required before navigating away."
        >
          <Dialog.Body>
            <div class="py-2 space-y-3">
              <p class="text-sm text-muted-foreground">
                {allowDismiss()
                  ? 'Press Escape or click the backdrop to dismiss.'
                  : 'Clicking outside or pressing Escape is blocked. Use the action buttons below.'}
              </p>
              <Show when={preventedAttempts() > 0}>
                <Badge variant="outline" class="text-danger border-danger">
                  Blocked {preventedAttempts()} outside dismissal attempt(s)
                </Badge>
              </Show>
            </div>
          </Dialog.Body>
          <Dialog.Footer>
            <div class="flex gap-2 w-full justify-end">
              <Button
                variant="outline"
                onClick={() => {
                  setOpen(false)
                  setPreventedAttempts(0)
                }}
              >
                Discard Changes
              </Button>
              <Button
                onClick={() => {
                  setOpen(false)
                  setPreventedAttempts(0)
                }}
              >
                Save & Apply
              </Button>
            </div>
          </Dialog.Footer>
        </Dialog.Content>
      </Dialog>
    </div>
  )
}

Read long release notes#

Use scrollable so long content scrolls with the overlay, or fullscreen for a full-viewport task.

import { Button, Dialog } from 'moraine'
import { For } from 'solid-js'

export function ScrollableFullscreen() {
  const SCROLLABLE_LINES = Array.from(
    { length: 100 },
    (_, index) => `Release note line ${index + 1}`,
  )

  return (
    <div class="flex flex-wrap gap-3 items-center">
      <Dialog scrollable>
        <Dialog.Trigger as={Button} variant="soft" tone="neutral">
          Overlay scroll dialog
        </Dialog.Trigger>
        <Dialog.Content title="Release Notes" description="Long content scrolls with the overlay.">
          <Dialog.Body>
            <div class="space-y-1">
              <For each={SCROLLABLE_LINES}>
                {(line) => <p class="text-sm text-foreground">{line}</p>}
              </For>
            </div>
          </Dialog.Body>
        </Dialog.Content>
      </Dialog>
      <Dialog fullscreen>
        <Dialog.Trigger as={Button} variant="soft" tone="neutral">
          Full screen dialog
        </Dialog.Trigger>
        <Dialog.Content title="Release Notes" description="Full screen dialog content.">
          <Dialog.Body>
            <div class="space-y-1">
              <For each={SCROLLABLE_LINES}>
                {(line) => <p class="text-sm text-foreground">{line}</p>}
              </For>
            </div>
          </Dialog.Body>
        </Dialog.Content>
      </Dialog>
    </div>
  )
}

Provision a cluster and wait for exit#

Open a provisioning dialog from its trigger. onExitComplete updates status after overlay and content finish their exit animations.

import { Badge, Button, Dialog } from 'moraine'
import { createSignal } from 'solid-js'

export function StructureLifecycle() {
  const [exits, setExits] = createSignal(0)
  const [status, setStatus] = createSignal('Idle')

  return (
    <div class="flex flex-wrap gap-4 items-center">
      <Dialog
        onExitComplete={() => {
          setExits((c) => c + 1)
          setStatus('Exit animation completed')
        }}
      >
        <Dialog.Trigger as={Button}>Open Provisioning Dialog</Dialog.Trigger>
        <Dialog.Content
          title="Provision Production Database"
          description="Configure clustering, replication nodes, and automated backup schedules."
        >
          <Dialog.Body>
            <div class="text-muted-foreground leading-relaxed py-2 space-y-2">
              <p>
                Provisioning will allocate dedicated compute instances and initialize encryption
                keys.
              </p>
            </div>
          </Dialog.Body>
          <Dialog.Footer>
            <div class="flex gap-2 w-full justify-end">
              <Button variant="outline">Cancel</Button>
              <Button>Provision Cluster</Button>
            </div>
          </Dialog.Footer>
        </Dialog.Content>
      </Dialog>

      <div class="text-xs text-muted-foreground flex gap-2 items-center">
        <span>Lifecycle status:</span>
        <Badge variant="outline">{status()}</Badge>
        <span>(Completed exits: {exits()})</span>
      </div>
    </div>
  )
}

Open a dialog from page state#

A page button owns open. The completed-exit count updates after exit motion finishes.

import { Button, Dialog } from 'moraine'
import { createSignal } from 'solid-js'

export function ControlledLifecycle() {
  const [open, setOpen] = createSignal(false)
  const [exitCount, setExitCount] = createSignal(0)

  return (
    <div class="flex gap-3 items-center">
      <Button variant="outline" onClick={() => setOpen(true)}>
        Open dialog
      </Button>
      <p class="text-sm text-muted-foreground">Completed exits: {exitCount()}</p>
      <Dialog
        open={open()}
        onOpenChange={setOpen}
        onExitComplete={() => setExitCount((count) => count + 1)}
      >
        <Dialog.Content title="Controlled dialog">
          <Dialog.Body>
            <p class="text-sm">The parent owns visibility and observes completed exit motion.</p>
          </Dialog.Body>
          <Dialog.Footer>
            <Button onClick={() => setOpen(false)}>Close</Button>
          </Dialog.Footer>
        </Dialog.Content>
      </Dialog>
    </div>
  )
}

API Reference#

Attributes#

Attributes
data-closed
Slot: dialog-triggerdialog-contentdialog-overlay
Description: Present when disclosure or transition content is closed.
data-disabled
Slot: dialog-trigger
Description: Present when the component, slot, or item is disabled.
data-expanded
Slot: dialog-triggerdialog-contentdialog-overlay
Description: Present when the panel, accordion, or menu is expanded.
data-overlay-scroll
Slot: dialog-overlay
Description: Present when scrolling is owned by the overlay.
data-transition
Slot: dialog-contentdialog-overlay
Description: Present while a target participates in a visibility transition.
data-footer
Slot: dialog-body
Description: Present when the component renders footer content.
data-header
Slot: dialog-body
Description: Present when the component renders header content.
data-scroll
Slot: dialog-body
Description: Present when the content region owns scrolling.

Props#

Dialog#

Prop

Trigger#

Renders a <button> element by default.

Prop

Content#

Props for Dialog.Content. Renders a <div> element by default.

Prop

Header#

Renders a <div> element by default.

Prop

Title#

Renders a <h2> element by default.

Prop

Description#

Renders a <p> element by default.

Prop

Body#

Renders a <div> element by default.

Prop

Renders a <div> element by default.

Prop

Close#

Renders a <button> element by default.

Prop