Notification

Feedback 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="notification": root · group · item · item-indicator · item-content · item-title · item-description · item-action-trigger · item-progress · item-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-notification>
Vue components	XhNotificationGroup XhNotificationItem XhNotificationItemActionTrigger XhNotificationItemCloseTrigger XhNotificationItemContent XhNotificationItemDescription XhNotificationItemIndicator XhNotificationItemProgress XhNotificationItemTitle XhNotificationRoot
Composable	useNotification
State machine	notificationMachine
Skin	@xihan-ui/styles/notification.css

Props

Prop	Type	Required
items	NotificationRecord[]
defaultItems	NotificationRecord[]
preset	NotificationPreset
placement	NotificationPlacement
max	number
dedupe	NotificationDedupe
gap	number
duration	number
stacked	boolean
pauseOnPageIdle	boolean
translations	Partial<NotificationTranslations>
onItemsChange	(details: NotificationItemsChangeDetails) => void

NotificationRecord

Elements of items.

Field	Type	Required
id	string	Yes
title	string
description	string
tone	NotificationTone
loading	boolean
duration	number
closable	boolean
placement	NotificationPlacement
actionLabel	string
priority	number
count	number

Events

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

Event	Payload
items-change	NotificationItemsChangeDetails

Slots

Only slots with a payload are listed.

Vue component	Slot	Payload
XhNotificationGroup	default	NotificationGroupSlotProps
XhNotificationItem	default	NotificationItemSlotProps
XhNotificationRoot	default	NotificationRootSlotProps

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
XhNotificationGroup	placement	NotificationPlacement
XhNotificationGroup	children	SlotChildren<NotificationGroupSlotProps>
XhNotificationItem	id	string
XhNotificationItem	preset	NotificationPreset
XhNotificationItem	title	string
XhNotificationItem	description	string
XhNotificationItem	tone	NotificationTone
XhNotificationItem	loading	boolean
XhNotificationItem	duration	number
XhNotificationItem	closable	boolean
XhNotificationItem	pauseOnPageIdle	boolean
XhNotificationItem	paused	boolean
XhNotificationItem	translations	NotificationItemProps['translations']
XhNotificationItem	onStatusChange	NotificationItemProps['onStatusChange']
XhNotificationItem	onAction	NotificationItemProps['onAction']
XhNotificationItem	children	SlotChildren<NotificationItemSlotProps>
XhNotificationRoot	children	SlotChildren<NotificationRootSlotProps>

State

Public state is written to data-state.

Part	Values
item	toStatus(state.get())
item-progress	toStatus(state.get())

The following names are internal to the state machine.

States: idle

Events: ITEMS.CREATE · ITEMS.UPDATE · ITEMS.DISMISS · ITEMS.DISMISS_ALL · STACK.EXPAND · STACK.COLLAPSE

connect API

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

Member	Type
preset	NotificationPreset
stacked	boolean
visibleNotifications	ResolvedNotification[]
placements	NotificationPlacement[]
count	number
getItemsByPlacement	(placement: NotificationPlacement) => ResolvedNotification[]
create	(options?: NotificationOptions) => string
update	(id: string, options: Partial<NotificationOptions>) => void
dismiss	(id: string) => void
dismissAll	() => void
getRootProps	() => T['element']
getGroupProps	(props?: NotificationGroupProps) => T['element']

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	notification.kbd.close
Enter / Space	notification.kbd.action
Enter / Space	notification.kbd.press
Escape	notification.kbd.collapse

ARIA

These attributes are produced by connect.

Part	Attribute	Value
group	aria-label	translations.region
group	role	'region'
item	aria-atomic	'true'
item	aria-describedby	id of the description part | undefined
item	aria-labelledby	id of the title part | undefined
item	aria-live	'assertive' | 'polite'
item	role	'alert' | 'status'
item-indicator	aria-hidden	'true'
item-progress	aria-hidden	'true'
item-close-trigger	aria-label	translations.close

Style reference

Skin

@xihan-ui/styles/notification.css is written against [data-scope="notification"][data-part="root"] part selectors; the published build uses the mount class .xh-scope-notification in place of data-scope (same specificity) and sits in the xihan.components and xihan.motion layers. 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
root	data-count	list.length
root	data-empty	'' (present only while the condition holds)
group	data-count	group.length
group	data-empty	'' (present only while the condition holds)
group	data-expanded	'' (present only while the condition holds)
group	data-placement	props.placement
group	data-preset	props.preset
group	data-stacked	'' (present only while the condition holds)
item	data-loading	'' (present only while the condition holds)
item	data-paused	'' (present only while the condition holds)
item	data-preset	props.preset
item	data-state	toStatus(state.get())
item	data-tone	props.tone
item	data-xh-loading-ring	''
item-indicator	data-loading	'' (present only while the condition holds)
item-indicator	data-xh-loading-ring	''
item-action-trigger	data-pressed	'' (present only while the condition holds)
item-action-trigger	data-xh-action-control	''
item-action-trigger	data-xh-action-display	'always'
item-action-trigger	data-xh-action-profile	'text'
item-action-trigger	data-xh-action-size	'sm'
item-action-trigger	data-xh-action-variant	'outline'
item-progress	data-state	toStatus(state.get())
item-close-trigger	data-disabled	'' (present only while the condition holds)
item-close-trigger	data-pressed	'' (present only while the condition holds)
item-close-trigger	data-xh-action-control	''
item-close-trigger	data-xh-action-display	'always'
item-close-trigger	data-xh-action-profile	'icon'
item-close-trigger	data-xh-action-size	'xs' | 'sm'
item-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-notification-action-bg	item-action-trigger	--xh-ink-surface background-color	default xh-ink-surface	transparent
--xh-notification-action-bg-active	item-action-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-bg-subtle-hover
--xh-notification-action-bg-hover	item-action-trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-bg-subtle
--xh-notification-action-border	item-action-trigger	border border-color	default disabled hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-border-control --xh-border-control-hover
--xh-notification-action-fg	item-action-trigger	color	default disabled hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-fg-default
--xh-notification-action-font-weight	item-action-trigger	font-weight	default	--xh-font-weight-medium
--xh-notification-action-h	item-action-trigger	block-size inline-size	default xh-action-profile=icon	--xh-_action-profile-visual-size
--xh-notification-action-px	item-action-trigger	padding-inline	default	--xh-_action-profile-padding-inline
--xh-notification-action-radius	item-action-trigger	border-radius	default	--xh-shape-control
--xh-notification-close-bg	item-close-trigger	--xh-ink-surface background-color	default xh-ink-surface	--xh-_action-variant-bg-rest
--xh-notification-close-bg-active	item-close-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-bg-pressed
--xh-notification-close-bg-hover	item-close-trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-_action-variant-bg-hover
--xh-notification-close-border	item-close-trigger	border	default	--xh-_action-variant-border-rest
--xh-notification-close-fg	item-close-trigger	color	default	--xh-fg-muted
--xh-notification-close-fg-hover	item-close-trigger	color	disabled hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-fg-default
--xh-notification-close-inset	item item-close-trigger item-title	inset-block-start inset-inline-end padding-inline-end	has([data-part='item-close-trigger']) preset=card	--xh-notification-item-py --xh-surface-action-inset
--xh-notification-close-radius	item-close-trigger	border-radius	default	--xh-shape-control
--xh-notification-close-size	item item-close-trigger item-title	block-size inline-size inset-block-start min-inline-size padding-inline-end	default has([data-part='item-close-trigger']) preset=card xh-action-profile=icon	--xh-_action-profile-visual-size --xh-control-h-sm
--xh-notification-description-fg	item item-description	color	default preset=toast	--xh-fg-default --xh-fg-muted
--xh-notification-description-font-size	item item-description	font-size	default preset=toast	--xh-text-body-size --xh-text-secondary-size
--xh-notification-description-leading	item item-description	line-height	preset=toast	--xh-leading-normal
--xh-notification-description-max-h	item-description	max-block-size	default	--xh-viewport-h-md
--xh-notification-icon-size	item item-action-trigger item-close-trigger	--xh-icon-size	default	--xh-_action-profile-glyph-size --xh-glyph-size-md --xh-glyph-size-xs
--xh-notification-indicator-fg	item item-indicator	background-color border border-color color	@media (prefers-reduced-motion: reduce) @media print default motion=reduce preset=toast where([data-motion='reduce']) xh-loading-ring xh-loading-ring=overlay	--xh-_tone-fg
--xh-notification-indicator-p	item item-indicator	padding	preset=toast	--xh-space-1
--xh-notification-indicator-size	item item-indicator	--xh-icon-size inline-size	default preset=toast	--xh-_notification-title-line --xh-glyph-size-md
--xh-notification-inset	group	inset-block-end inset-block-start inset-inline-end inset-inline-start padding-block-end padding-block-start padding-inline	default not([data-stacked]) placement=-end placement=-start placement=bottom placement=top preset=toast stacked	--xh-space-4 --xh-space-6
--xh-notification-item-bg	item	background	default	--xh-material-elevated-bg
--xh-notification-item-border	item	border	default	--xh-material-elevated-border
--xh-notification-item-fg	item	color	default	--xh-material-elevated-fg
--xh-notification-item-font-size	item	font-size	default preset=toast	--xh-text-body-size --xh-text-label-size
--xh-notification-item-gap	item	column-gap	default preset=toast	--xh-space-2 --xh-space-3
--xh-notification-item-leading	item	line-height	default	--xh-text-body-leading
--xh-notification-item-px	item	inset-inline-start padding-inline	default preset=toast	--xh-overlay-notification-p --xh-space-4
--xh-notification-item-py	item item-close-trigger	inset-block-start padding-block	default preset=card preset=toast	--xh-overlay-notification-p --xh-space-2_5
--xh-notification-item-radius	item	border-radius	default preset=toast	--xh-shape-control --xh-shape-sheet
--xh-notification-item-row-gap	item item-content	row-gap	default	--xh-space-2
--xh-notification-item-shadow	item	box-shadow	default	--xh-material-elevated-shadow
--xh-notification-item-w	group item	inline-size	default preset=toast stacked	--xh-overlay-notification-w --xh-overlay-toast-w
--xh-notification-layer	group	z-index	default	--xh-layer-toast
--xh-notification-progress-bg	item-progress	background	default	--xh-_tone-soft
--xh-notification-progress-duration	item-progress	animation	default	--xh-motion-duration-slide
--xh-notification-progress-radius	item item-progress	border-radius clip-path	@keyframes xh-countdown preset=card	--xh-shape-pill
--xh-notification-progress-thickness	item-progress	block-size	default	--xh-space-0_5
--xh-notification-stack-scale	* group item	scale	@keyframes xh-notification-stack-in @keyframes xh-notification-stack-out preset=toast stacked	--xh-_notification-stack-scale
--xh-notification-title-fg	item item-title	color	default preset=toast	--xh-_tone-fg --xh-fg-default
--xh-notification-title-font-size	item item-close-trigger item-indicator item-title	--xh-icon-size block-size font-size inline-size inset-block-start	default preset=card preset=toast	--xh-text-body-size --xh-text-heading-3-size
--xh-notification-title-font-weight	item item-title	font-weight	default preset=toast	--xh-font-weight-medium --xh-text-heading-3-weight
--xh-notification-title-leading	item item-close-trigger item-title	inset-block-start line-height	default preset=card preset=toast	--xh-leading-normal --xh-leading-tight