Dialog

Overlays component. This page is the API reference, generated from the source code. Usage guidance and live examples are on the Chinese page.

HeadlessStylesVueReactWeb Components

Anatomy

Parts in bold are required.

data-scope="dialog": trigger · backdrop · positioner · content · header · drag-trigger · indicator · title · description · body · footer · confirm-trigger · cancel-trigger · close-trigger

API reference

Descriptions of individual props, events and slots are written in Chinese and appear on the Chinese page.

Artifacts

Layer	Value
Custom element	<xh-dialog>
Vue components	XhDialogBody XhDialogCancelTrigger XhDialogCloseTrigger XhDialogConfirmTrigger XhDialogContent XhDialogDescription XhDialogDragTrigger XhDialogFooter XhDialogHeader XhDialogIndicator XhDialogRoot XhDialogTitle XhDialogTrigger
Composable	useDialog
State machine	dialogMachine
Skin	@xihan-ui/styles/dialog.css

Props

Prop	Type	Required
open	boolean
defaultOpen	boolean
modal	boolean
role	'dialog' | 'alertdialog'
closeOnEscape	boolean
closeOnInteractOutside	boolean
restoreFocus	boolean
initialFocus	string
size	Size
variant	OverlayBackdropVariant
draggable	boolean
unmountOnExit	boolean
parts	TitleDescriptionParts
translations	Partial<DialogTranslations>
onOpenChange	(details: DialogOpenChangeDetails) => void
onExitComplete	() => void

Events

Custom elements put the payload in detail; Vue emits an event of the same name.

Event	Payload
confirm	CustomEvent
confirm-error	CustomEvent
cancel-press	CustomEvent
exit-complete	CustomEvent
open-change	DialogOpenChangeDetails

Slots

Only slots with a payload are listed.

Vue component	Slot	Payload
XhDialogRoot	default	DialogRootSlotProps
XhDialogRoot	trigger	—
XhDialogRoot	title	—
XhDialogRoot	description	—
XhDialogRoot	body	—
XhDialogRoot	footer	—

React adapter props

Only the props each component declares itself: DOM attributes inherited from ComponentPropsWithRef are left out, and root props already listed in the Props table are not repeated. The Vue counterpart is the slot table above.

React component	Prop	Type	Required
XhDialogContent	container	() => Element | null
XhDialogRoot	trigger	ReactNode
XhDialogRoot	title	ReactNode
XhDialogRoot	description	ReactNode
XhDialogRoot	body	ReactNode
XhDialogRoot	footer	ReactNode
XhDialogRoot	actions	DialogStructureActions
XhDialogRoot	confirmText	string
XhDialogRoot	cancelText	string
XhDialogRoot	onConfirm	DialogActionIntents['onConfirm']
XhDialogRoot	onConfirmError	DialogActionIntents['onConfirmError']
XhDialogRoot	onCancelPress	DialogActionIntents['onCancelPress']
XhDialogRoot	children	SlotChildren<DialogRootSlotProps>

State

Public state is written to data-state.

Part	Values
trigger	'open' | 'closed'
backdrop	'open' | 'closed'
positioner	'open' | 'closed'
content	'open' | 'closed'

The following names are internal to the state machine.

States: open · closed

Events: OPEN · TOGGLE · CLOSE · CONTROLLED.OPEN · CONTROLLED.CLOSE · PRESS.START · PRESS.END · DRAG.START · DRAG.NUDGE · DRAG.RESET · GESTURE.MOVE · GESTURE.END

Guards: isOpenControlled · canDrag

connect API

getXxxProps() returns the host attributes of the matching part.

Member	Type
open	boolean
offset	DialogOffset
dragging	boolean
pending	boolean
actionError	DialogConfirmErrorDetails | null
setOpen	(next: boolean) => void
confirm	() => void
cancel	() => void
getTriggerProps	() => T['button']
getBackdropProps	() => T['element']
getPositionerProps	() => T['element']
getContentProps	() => T['element']
getHeaderProps	() => T['element']
getDragTriggerProps	() => T['button']
getIndicatorProps	() => T['element']
getTitleProps	() => T['element']
getDescriptionProps	() => T['element']
getBodyProps	() => T['element']
getFooterProps	() => T['element']
getConfirmTriggerProps	() => T['button']
getCancelTriggerProps	() => T['button']
getCloseTriggerProps	() => T['button']
isContentMounted	(present: boolean) => boolean

Accessibility

Keyboard

Specification: W3C APG. Each row is a stable behavior id that the conformance tests cover; the conditions and effects are described on the Chinese page.

Keys	Behavior
Enter / Space	dialog.kbd.open-on-trigger
Escape	dialog.kbd.escape
Tab	dialog.kbd.tab
Shift+Tab	dialog.kbd.shift-tab
Enter / Space	dialog.kbd.press
ArrowUp / ArrowDown / ArrowLeft / ArrowRight	dialog.kbd.drag-move
Shift+ArrowUp / Shift+ArrowDown / Shift+ArrowLeft / Shift+ArrowRight	dialog.kbd.drag-large
Enter / Space	dialog.kbd.drag-reset

ARIA

These attributes are produced by connect.

Part	Attribute	Value
trigger	aria-controls	id of the content part
trigger	aria-expanded	'true' | 'false'
trigger	aria-haspopup	'dialog'
content	aria-describedby	id of the description part | undefined
content	aria-hidden	!open || undefined
content	aria-labelledby	id of the title part | undefined
content	aria-modal	'true' | 'false'
content	role	props.role
drag-trigger	aria-disabled	'false' | 'true'
drag-trigger	aria-label	translations.dragTrigger
indicator	aria-hidden	'true'
confirm-trigger	aria-busy	'true' | undefined
confirm-trigger	aria-disabled	'true' | undefined
close-trigger	aria-label	translations.close

Style reference

Skin

@xihan-ui/styles/dialog.css is written against [data-scope="dialog"][data-part="trigger"] part selectors; the published build uses the mount class .xh-scope-dialog in place of data-scope (same specificity) and sits in the xihan.components layer. Put overrides in xihan.overrides; the part selectors work as usual.

Data attributes

Produced by connect; valueless attributes are omitted while their condition does not hold.

Part	Attribute	Value
trigger	data-pressed	'' (present only while the condition holds)
trigger	data-state	'open' | 'closed'
trigger	data-xh-action-control	''
trigger	data-xh-action-display	'always'
trigger	data-xh-action-profile	'text'
trigger	data-xh-action-size	'md'
trigger	data-xh-action-variant	'outline'
backdrop	data-instant	'' (present only while the condition holds)
backdrop	data-state	'open' | 'closed'
backdrop	data-variant	props.variant
positioner	data-positioned	''
positioner	data-state	'open' | 'closed'
content	data-draggable	'' (present only while the condition holds)
content	data-dragging	'' (present only while the condition holds)
content	data-instant	'' (present only while the condition holds)
content	data-size	props.size
content	data-state	'open' | 'closed'
header	data-draggable	'' (present only while the condition holds)
drag-trigger	data-disabled	'' (present only while the condition holds)
drag-trigger	data-dragging	'' (present only while the condition holds)
title	data-draggable	'' (present only while the condition holds)
confirm-trigger	data-loading	'' (present only while the condition holds)
confirm-trigger	data-pressed	'' (present only while the condition holds)
confirm-trigger	data-xh-action-control	''
confirm-trigger	data-xh-action-display	'always'
confirm-trigger	data-xh-action-profile	'text'
confirm-trigger	data-xh-action-size	'md'
confirm-trigger	data-xh-action-variant	'solid'
confirm-trigger	data-xh-ink-surface	''
confirm-trigger	data-xh-loading-ring	'overlay'
cancel-trigger	data-pressed	'' (present only while the condition holds)
cancel-trigger	data-xh-action-control	''
cancel-trigger	data-xh-action-display	'always'
cancel-trigger	data-xh-action-profile	'text'
cancel-trigger	data-xh-action-size	'md'
cancel-trigger	data-xh-action-variant	'outline'
close-trigger	data-pressed	'' (present only while the condition holds)
close-trigger	data-xh-action-control	''
close-trigger	data-xh-action-display	'always'
close-trigger	data-xh-action-profile	'icon'
close-trigger	data-xh-action-size	'sm'
close-trigger	data-xh-action-variant	'ghost'

CSS variables

The public override slots, generated from what the standalone skin actually consumes.

Variable	Part	CSS property	State	Default from
--xh-dialog-backdrop-bg	backdrop	background	default	--xh-bg-overlay
--xh-dialog-backdrop-blur	backdrop	-webkit-backdrop-filter backdrop-filter	variant=blur	--xh-overlay-backdrop-blur
--xh-dialog-backdrop-filter	backdrop content	-webkit-backdrop-filter backdrop-filter	default variant=blur	--xh-dialog-backdrop-blur --xh-material-elevated-backdrop
--xh-dialog-backdrop-layer	backdrop	z-index	default	--xh-_layer
--xh-dialog-bg	content	background	default	--xh-material-elevated-bg
--xh-dialog-body-px	body	padding-inline	default	--xh-overlay-sheet-px
--xh-dialog-body-py	body	padding-block	default	--xh-overlay-sheet-body-py
--xh-dialog-border	content	border	default	--xh-material-elevated-border
--xh-dialog-close-bg-active	close-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-bg-pressed
--xh-dialog-close-bg-focus	close-trigger	background-color	focus-visible	--xh-_action-variant-bg-focus-visible
--xh-dialog-close-bg-hover	close-trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-_action-variant-bg-hover
--xh-dialog-close-fg	close-trigger	color	default	--xh-fg-muted
--xh-dialog-close-fg-focus	close-trigger	color	focus-visible	--xh-dialog-close-fg-hover
--xh-dialog-close-fg-hover	close-trigger	color	disabled focus-visible hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-fg-focus-visible --xh-_action-variant-fg-hover --xh-_action-variant-fg-pressed
--xh-dialog-close-radius	close-trigger	border-radius	default	--xh-shape-control
--xh-dialog-close-size	close-trigger content title	block-size inline-size inset-block-start padding-inline-end	default has([data-scope='dialog'][data-part='close-trigger']) xh-action-profile=icon	--xh-_action-profile-visual-size --xh-control-h-sm
--xh-dialog-content-backdrop-filter	content	-webkit-backdrop-filter backdrop-filter	default	--xh-dialog-backdrop-filter
--xh-dialog-description-fg	description	color	default	--xh-fg-muted
--xh-dialog-description-font-size	description	font-size	default	--xh-text-secondary-size
--xh-dialog-drag-trigger-min-h	drag-trigger	min-block-size	default	--xh-space-6
--xh-dialog-drag-trigger-radius	drag-trigger	border-radius	default	--xh-shape-control
--xh-dialog-fg	content	color	default	--xh-material-elevated-fg
--xh-dialog-footer-gap	footer	gap	default	--xh-control-gap-md
--xh-dialog-footer-pt	footer	padding-block-start	default	--xh-space-2
--xh-dialog-footer-px	content footer	padding-inline	has([data-scope='dialog'][data-part='body'])	--xh-overlay-sheet-px
--xh-dialog-footer-py	content footer	padding-block	has([data-scope='dialog'][data-part='body'])	--xh-overlay-sheet-footer-py
--xh-dialog-gap	content	gap	default	--xh-stack-gap-md
--xh-dialog-header-gap	header	gap	default	--xh-stack-gap-sm
--xh-dialog-header-pb	content header	padding-block-end	default has([data-scope='dialog'][data-part='body'])	--xh-_dialog-header-pb --xh-space-2
--xh-dialog-header-pt	content header	padding-block-start	has([data-scope='dialog'][data-part='body'])	--xh-_dialog-header-pt
--xh-dialog-header-px	content header	padding-inline	has([data-scope='dialog'][data-part='body'])	--xh-overlay-sheet-px
--xh-dialog-icon-size	close-trigger content trigger	--xh-icon-size	default	--xh-_action-profile-glyph-size --xh-glyph-size-md --xh-glyph-size-xs
--xh-dialog-indicator-bg	indicator	background	default	--xh-_tone-subtle
--xh-dialog-indicator-fg	indicator	color	default	--xh-_tone-fg
--xh-dialog-indicator-mark-size	indicator	--xh-icon-size	default	--xh-dialog-indicator-size
--xh-dialog-indicator-radius	indicator	border-radius	default	--xh-shape-circle
--xh-dialog-indicator-size	indicator	--xh-icon-size block-size inline-size	default	--xh-glyph-size-md
--xh-dialog-layer	positioner	z-index	default	--xh-_layer
--xh-dialog-max-w	content	max-inline-size	default	--xh-_dialog-max-w
--xh-dialog-positioner-padding	positioner	padding-block-end padding-block-start padding-inline	default	--xh-space-4
--xh-dialog-px	content	padding-inline	default	--xh-overlay-sheet-px
--xh-dialog-py	content	padding-block-end padding-block-start	default	--xh-_dialog-header-pt --xh-overlay-sheet-body-py
--xh-dialog-radius	content	border-radius	default	--xh-shape-sheet
--xh-dialog-separator	content footer header	border-block-end border-block-start	has([data-scope='dialog'][data-part='body']) has([data-scope='dialog'][data-part='footer'])	--xh-material-elevated-separator
--xh-dialog-shadow	content	box-shadow	default	--xh-material-elevated-shadow
--xh-dialog-title-fg	title	color	default	--xh-fg-default
--xh-dialog-title-font-size	title	font-size	default	--xh-text-heading-3-size
--xh-dialog-title-font-weight	title	font-weight	default	--xh-text-heading-3-weight