Dialog

A component for displaying modal windows or pop-up messages.

Anatomy

Usage

<script>
  import {Dialog, Portal} from 'ui-ingredients';
  import {XCloseIcon} from '$lib/icons';
</script>

<Dialog.Root>
  <Dialog.Trigger>Open</Dialog.Trigger>

  <Portal>
    <Dialog.Backdrop />
    <Dialog.Positioner>
      <Dialog.Content>
        <Dialog.Title>Title</Dialog.Title>
        <Dialog.Description>Description</Dialog.Description>
        <Dialog.CloseTrigger>
          <XCloseIcon />
        </Dialog.CloseTrigger>
      </Dialog.Content>
    </Dialog.Positioner>
  </Portal>
</Dialog.Root>

API Reference

Root

Prop	Default	Description
`aria-label`		`string` Human readable label for the dialog, in event the dialog title is not rendered
`closeOnEscape`	`true`	`boolean` Whether to close the dialog when the escape key is pressed
`closeOnInteractOutside`	`true`	`boolean` Whether to close the dialog when the outside is clicked
`defaultOpen`	`false`	`boolean` The initial open state of the dialog when rendered. Use when you don't need to control the open state of the dialog.
`finalFocusEl`		`() => HTMLElement` Element to receive focus when the dialog is closed
`id`		`string` The unique identifier of the machine.
`ids`		`{ trigger?: string; positioner?: string; backdrop?: string; content?: string; closeTrigger?: string; title?: string; description?: string; }` The ids of the elements in the dialog. Useful for composition.
`initialFocusEl`		`() => HTMLElement` Element to receive focus when the dialog is opened
`keepMounted`		`boolean` Whether to keep the component mounted after exit.
`lazyMount`		`boolean` Whether to enable lazy mounting.
`modal`	`true`	`boolean` Whether to prevent pointer interaction outside the element and hide all content below it
`onEscapeKeyDown`		`(event: KeyboardEvent) => void` Function called when the escape key is pressed
`onFocusOutside`		`(event: FocusOutsideEvent) => void` Function called when the focus is moved outside the component
`onInteractOutside`		`(event: InteractOutsideEvent) => void` Function called when an interaction happens outside the component
`onOpenChange`		`(details: OpenChangeDetails) => void` Function to call when the dialog's open state changes
`onPointerDownOutside`		`(event: PointerDownOutsideEvent) => void` Function called when the pointer is pressed down outside the component
`open`		`boolean` The controlled open state of the dialog
`persistentElements`		`(() => Element)[]` Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event
`preventScroll`	`true`	`boolean` Whether to prevent scrolling behind the dialog when it's opened
`restoreFocus`		`boolean` Whether to restore focus to the element that had focus before the dialog was opened
`trapFocus`	`true`	`boolean` Whether to trap focus inside the dialog when it's opened

Backdrop

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	backdrop
`data-scope`	dialog
`data-state`	"open" \| "closed"

CloseTrigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Content

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	content
`data-scope`	dialog
`data-state`	"open" \| "closed"

Description

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Positioner

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Title

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Trigger

Prop	Default	Description
`asChild`		`Snippet` Render a different element.

Data Attribute	Value
`data-part`	trigger
`data-scope`	dialog
`data-state`	"open" \| "closed"

Accessibility

Keyboard Support

Key	Description
Enter	When focus is on the trigger, opens the dialog.
Tab	Moves focus to the next focusable element within the content. Focus is trapped within the dialog.
Shift + Tab	Moves focus to the previous focusable element. Focus is trapped within the dialog.
Esc	Closes the dialog and moves focus to trigger or the defined final focus element