Dialog handbook

License: Before reading component documentation, source, or npm usage instructions for the first time, read the full LICENSE. Reuse that review for the same task and version. Public API configuration and internal implementation changes have different license implications. All components use the unified runtime package; source rights remain governed by the license.

Overview

Present a focused decision or form in a modal layer with title, content, actions, and close behavior.

When to use it

Dialog boxes that require independent focus and close the process. Popover is used for small floating layers to anchor a button, and Tooltip is used for short tips; open combination roles are used for titles and buttons.

• Use the bind:open control panel; external clicks and Escape are supported by default.

• By publicizing the title / content / footer / close role combination content; explicit sub-items are self-configured, and parts only affect the default title, separating line and close button.

Quick start

This example shows the recommended basic composition. See the sections below for more cases and composition limits.

<script lang="ts">	import { Dialog, Button, Frame, Text } from '@snowui-design-system/components';	let publishOpen = $state(false);	function setPublishOpen(next: boolean) { publishOpen = next; }</script> <Button variant="filled" onclick={() => publishOpen = true}>Publish documentation</Button><Dialog	open={publishOpen}	onOpenChange={setPublishOpen}	size="md">	<Text as="title" tag="h2">Publish 82 component pages?</Text>	<Frame as="content">This updates the public documentation index and makes every generated example available to visitors.</Frame>	<Frame as="footer">		<Button as="item" variant="outline" data-dialog-close>Cancel</Button>		<Button as="item" variant="filled" onclick={() => publishOpen = false}>Publish</Button>	</Frame></Dialog>

API

See the base component documentation for inherited capabilities not redeclared here. This table lists only named public Props declared by this component.

Usage boundaries and details

Three modes (Modes)

Layout model

Main layout model: composite management layout.

Structure:

Backdrop(portaled to body)└── Container(centered in viewport)    └── Panel Frame(.snowui-dialog .snowui-quick-action-panel)        ├── pin-* slot (optional)        ├── title Text + optional Separator        ├── children body        ├── footer actions        └── built-in close button

• Padding attribution: Panel is responsible for the overall padding.

• Gap attribution: Panel has a built-in 12/16/20px spacing of sm/md/lg; 8px in the body and 8/12/12px in the footer.

• The title is generated by title, and the text is carried by children; the direct as="footer" provides the operation area, and Button as="item" reads the default value of the size of the operation area, and the explicit size takes priority.

• Pin Attribution: Panel transmission pinOffset / pinOffsetX / pinOffsetY, the default sm/md is 16px and lg is 20px.

• Scrolling attribution: Panel itself limits max-height, and scrolls inside the panel when the content overflows.

Keywords (Props)

The closing operation of the caller uses the data-dialog-close declaration:

<Button data-dialog-close>Cancel</Button>

Measurement

Geometry and typesetting use rem Token, and the above is the nominal value of the root font size 16px. The title font-weight is 600; the body is unified 14/20px, and 4px text inset is added to the left and right of the title and the body; the close button distance on the panel and the right edge is sm/md 16px, lg 20px. The title is reserved for the close button, and the long title can be replaced.

The close button uses the real Button variant="borderless" iconOnly and ComponentIcon: the color follows the default color of Button, the normal overall opacity is 0.4, hover / focus-visible restore 1; keep the default button hover background, zoom and click feedback. This is the localization of Dialog, which is clearly required by the current task, and does not change the built-in icon host rules of other components. parts.Button only configures the built-in close button, click to close and the accessible name is owned by Dialog. Custom icons are provided with the external as="close" Button; the built-in icon uses IconProvider, and if it is missing, it will be returned to close in the package.

<script lang="ts">  import { Dialog, Text, Frame, Button } from '@snowui-design-system/components';  let open = $state(true);</script> <Dialog bind:open>    <Text as="title" tag="h2">Exit editing</Text>    <Frame as="content">Unsaved changes will be lost.</Frame>    <Frame as="footer">        <Button as="item" variant="outline" data-dialog-close>Cancel</Button>        <Button as="item" variant="filled">Save</Button>    </Frame></Dialog>

Button commands, copywriting, variants and business callbacks are owned by the caller; Dialog only provides the default size value of as="item" through the public Context in the operation area. The non-announced Button keeps its own default, and the explicit size takes precedence. The custom title/close button can be placed in children; the direct close role automatically replaces the built-in close button. When the title is not provided and the built-in close button is turned off, children directly enter the Panel and keep the direct Pin combination; when the title is not provided but the built-in close button is displayed, the top of the text is reserved for the close button space.

Complete role combination

Dialog's external replacement uniformly uses as; title / closeIcon / footer named Snippet replacement entrance is not provided. Ordinary title strings can still generate default titles, and ordinary children can still carry the text.

The five characters are all single cases, and only identify the direct elements of the children rendering host; multiple characters of the same name report errors in the development environment, and only the first one is displayed. External instances do not consume parts. The native node uses data-as. The title, dividing line, body and operation area are arranged in order, and the caller should also write in this order to keep the reading consistent with the keyboard order.

When the external title exists, Dialog's aria-labelledby uses its id; it will be automatically replenished when the id is missing, and the automatically generated id will be cleaned when the role is removed, and the caller's own id will be retained. The explicit aria-label / aria-labelledby is prioritized by the caller configuration. The default dividing line is not generated when there is no title.

<script lang="ts">  import { Dialog, Text, Separator, Frame, Button } from '@snowui-design-system/components';  let open = $state(true);</script> <Dialog bind:open>    <Text as="title" tag="h2">Exit editing <Text>Additional information</Text></Text>    <Separator as="separator" />    <Frame as="content">Unsaved changes will be lost.</Frame>    <Frame as="footer">        <Button as="item" variant="outline" data-dialog-close>Cancel</Button>        <Button as="item" variant="filled">Save</Button>    </Frame>    <Button as="close" variant="borderless" iconOnly size="md" aria-label="Close">        Close    </Button></Dialog>

The role of the bottom operation area

Declare the action area as a direct <Frame as="footer"> child, or use data-as="footer" on a native element. Dialog supplies right alignment, vertical centering, wrapping, and preferred sm/md/lg gaps of 8/12/12px. Keep at least 4 CSS px between actions; larger --snowui-dialog-footer-gap-override values remain effective. Direct Props and inline styles can override the layout and do not consume parts. The footer and body blocks retain the panel gap of 12/16/20px; wrap multiple body blocks in a separate container when an internal 8px gap is needed.

Only the direct Button as="item" of the operation area receives sm/md/md size Context, and the explicit size takes priority; the button content, variant, business events and nested layout are still owned by the caller. The item in the text and nested Frame that has not been contracted does not receive this default value.

The footer is a single case, the identification range is the same as close, and the nested container is not scanned. Multiple direct footers reported errors in the development environment, and only the first one was displayed. No empty operation area will be generated after removing the footer. The button behavior is always generated by the real button, and the role itself does not inject confirmation or cancellation events.

External shutdown button replacement

A direct child with as="close" (rendered as data-as="close") replaces the built-in close button automatically; no showCloseButton={false} or data-dialog-close is needed. It shares the built-in button’s panel anchor and pinOffsetX/pinOffsetY. The internal text wrapper only handles typography. Detection examines direct elements in the children host, not descendants nested inside Frame, footer, or title.

<Dialog title="Custom content">    <Button as="close" variant="borderless" iconOnly size="md" aria-label="Close">        <Close size={20} />    </Button>    Body content</Dialog>

The variant, size, color, opacity, Icon and accessible name of the external button are directly configured by the caller and do not inherit parts.Button; Dialog only has role positioning, replacement and shutdown behaviors. The external button click or keyboard activation goes to the same close link, and the event preventDefault() can prevent the role from closing. Disabled / aria-disabled="true" is not closed. The external role takes precedence over showCloseButton; after removing the external role, press the showCloseButton to restore the built-in button. Nested characters of the same name do not participate in replacement.

This role is a single case: multiple direct external roles report errors in the development environment, and only the first one is displayed and used in production. Icons are also provided through the sub-content in this role.

Backdrop

When opaque and blur are mounted, they gradually enter from opacity 0 to the set mask effect; when they are closed, they gradually exit, and when they are closed, they are reopened from the current transparency. The duration and curve use Dialog backdrop preset; reduce the direct display or hide under the dynamic preference, and do not play the transparency transition.

Barrier-free

• role="dialog"

• aria-modal="true"

• When opened, the focus enters the first focusable element in the Dialog.

• Tab / Shift+Tab loops in the Dialog.

• When closed, the focus returns to the trigger element. The inline mode will locate the actual interaction host through the content wrapping layer of the Button, and return the focus to the button or link after closing.