Dialog

Modal dialog with focus containment and configurable dismissal.

Overview

  • Use a dialog for a focused task or decision that interrupts the page.

Aliases

modal

When to use

  • Use Dialog for blocking confirmations, brief forms, or focused review tasks.
  • Provide a title and description that explain the decision.

When not to use

  • Do not use Dialog for passive status messages; use Alert or Toast.
  • Use Drawer for supporting tasks that need more page context.

Structural parts

open control

trigger

Control that opens the dialog.

modal container

surface

Contains title, description, body, and footer.

actions row

footer

Optional closing actions area.

Public interface

Props
NameTypeDefaultDescription
openbooleanfalseControlled open state.
size'sm' | 'md' | 'lg''md'Chooses the dialog size recipe.
titlestring—Dialog title.
descriptionstring—Optional supporting explanation.
closeOnEscapebooleantrueAllows Escape to close the dialog.
closeOnOutsidePressbooleantrueAllows outside press dismissal.
onOpenChange(detail: { open: boolean }) => void—Runs when the dialog opens or closes.
themeThemeContract—Sets the theme used to resolve component styles.
Events
NamePayloadDescription
openchange{ open: boolean }Fires when an overlay-style component opens or closes through user interaction.
Slots
NameDescription
triggerOptional trigger content.
defaultDialog body content.
footerOptional footer actions.

Variants, sizes, and states

Variants

  • modal: Centered blocking overlay surface.

Sizes

  • sm: Compact modal
  • md: Default modal
  • lg: Larger modal for more content

States

  • closed: Dialog is hidden
  • open: Dialog is visible and focus-contained

Accessibility

Semantics

  • Uses overlay semantics that reflect whether the surface is modal, contextual, or advisory.
  • Uses dialog semantics with labeled title and optional description.

Keyboard

  • Supports Escape dismissal when allowed.
  • Returns focus to the trigger after closing.
  • Focus moves into the dialog on open and returns to the trigger on close.

Screen readers

  • Announces the overlay surface with its title, description, or tooltip content as available.

Checklist

  • Verify that the control has an accessible name.
  • Verify that keyboard focus is visible in every state and size.
  • Identify disabled, selected, and error states with text or symbols as well as color.

Tokens and CSS variables

root

--dk-motion-duration
200ms

backdrop

--dk-dialog-backdrop-bg
rgba(15, 23, 42, 0.45)

surface

--dk-dialog-surface-bg
#f2f5fb
--dk-dialog-surface-fg
#16181c
--dk-dialog-surface-border
#95989d
--dk-dialog-surface-radius
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)
--dk-dialog-surface-shadow
0 10px 15px rgba(0, 0, 0, 0.06), 0 4px 6px rgba(0, 0, 0, 0.04)
--dk-dialog-surface-width
420px
--dk-dialog-surface-padding
clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)

title

--dk-dialog-title-size
clamp(1.778rem, 1.6296rem + 0.658vw, 2.222rem)
--dk-dialog-title-weight
650

description

--dk-dialog-description-size
clamp(1.333rem, 1.2222rem + 0.494vw, 1.667rem)

footer

--dk-dialog-footer-gap
clamp(0.75rem, 0.6875rem + 0.278vw, 0.938rem)

Implementation notes

  • Dialog is modal. Use Popover for contextual content that does not block the page.

Examples

Starter

Confirm action

A dialog for reviewing a decision.

<Dialog title="Release notes" description="Confirm the publication details before shipping."><svelte:fragment slot="trigger">Open dialog</svelte:fragment>Review the release details.</Dialog>

Common patterns

Explicit footer actions

Use a footer when the decision needs multiple clear next steps.

<Dialog title="Confirm delete"><svelte:fragment slot="footer"><Button variant="ghost">Cancel</Button><Button variant="destructive">Delete</Button></svelte:fragment>Review the consequences before continuing.</Dialog>

Edge cases

Controlled modal state

Control open state when product logic owns the workflow.

<Dialog open={isOpen} onOpenChange={(detail) => isOpen = detail.open} title="Release notes">Review details</Dialog>

Mathematical fixtures

Calculated fixtures; browser evidence is not collected. Layout estimates use declared text behavior and maximum token values.

default (size=sm)

pass

size=sm

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, layout
  • Evaluated: contrast, layout
  • Contrast: 98.5 Lc
  • Layout: surface · single-line 0 px single-line estimate; 0 px minimum width
    360 px: pass 420 px: pass 560 px: pass

default (size=md)

pass

size=md

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, layout
  • Evaluated: contrast, layout
  • Contrast: 98.5 Lc
  • Layout: surface · single-line 0 px single-line estimate; 0 px minimum width
    360 px: pass 420 px: pass 560 px: pass

large

pass

size=lg

  • Evidence: mathematical
  • Coverage: complete (2 / 2 declared kinds evaluated)
  • Declared: contrast, layout
  • Evaluated: contrast, layout
  • Contrast: 98.5 Lc
  • Layout: surface · single-line 0 px single-line estimate; 0 px minimum width
    360 px: pass 420 px: pass 560 px: pass