Dialog

An accessible modal pattern with trigger, portal, overlay, and content parts. It includes nested dialog stacking so only the topmost dialog handles global close interactions.

Anatomy

All parts live inside Dialog.Root. Dialog.Trigger opens the dialog, and the modal layers — Dialog.Overlay and Dialog.Content — render inside Dialog.Portal. The root children snippet receives state helpers (close, open, toggle, isOpen).

<script>
	import { Dialog } from '@human-kit/ui';
</script>

<Dialog.Root>
	{#snippet children({ close })}
		<Dialog.Trigger>Open</Dialog.Trigger>
		<Dialog.Portal>
			<Dialog.Overlay />
			<Dialog.Content>...</Dialog.Content>
		</Dialog.Portal>
	{/snippet}
</Dialog.Root>

Controlled state

Bind open on Dialog.Root to drive the dialog from outside — a trigger is optional. defaultOpen covers the uncontrolled case, and onOpenChange reports every change.

Nested dialogs

Nest a Dialog.Root inside another dialog's content to build modal stacks. The stack is managed internally: overlays and panels get increasing z-indexes, and Escape or outside clicks only close the topmost dialog.

Usage guidelines

• Place all dialog parts inside Dialog.Root.
• Use Dialog.Trigger as the opener button.
• Render modal layers inside Dialog.Portal.
• Use Dialog.Overlay and Dialog.Content together for standard modal behavior.
• Use nested Dialog.Root instances when you need modal stacks; topmost behavior is handled internally.
• Use shouldCloseOnEscape / shouldCloseOnInteractOutside on Dialog.Content to opt out of the default close interactions.

Accessibility

• Dialog.Content renders role="dialog" with aria-modal="true" while open.
• Focus is trapped inside the open dialog, and content outside it is hidden from assistive technology.
• Body scroll is locked while a modal dialog is open.
• Escape closes the topmost dialog; closing returns focus to the trigger.

API reference

Root

State container for the dialog. Holds open state and the trigger reference, and passes state helpers ({ close, open, toggle, isOpen }) to its children snippet.

* required. Native HTML attributes of the underlying element are also accepted.

Trigger

Button that registers itself as the dialog trigger and toggles the dialog on click.

* required. Native HTML attributes of the underlying element are also accepted.

Portal

Portal wrapper that renders the dialog layers into the document body only while the dialog is open (staying mounted through exit animations).

* required. Native HTML attributes of the underlying element are also accepted.

Overlay

Backdrop layer rendered behind the dialog content. Its z-index is derived from the dialog's position in the stack.

* required. Native HTML attributes of the underlying element are also accepted.

Content

The modal panel (role="dialog", aria-modal). Applies focus trapping, outside-interaction handling, scroll lock, and aria-hiding of outside content; close interactions only apply to the topmost dialog in a stack.

* required. Native HTML attributes of the underlying element are also accepted.

Title

* required. Native HTML attributes of the underlying element are also accepted.

Description

* required. Native HTML attributes of the underlying element are also accepted.

Close

* required. Native HTML attributes of the underlying element are also accepted.