CalendarPicker

Data entry 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="calendar-picker": root · header · prev-year-trigger · prev-trigger · next-trigger · next-year-trigger · heading · heading-year-trigger · heading-month-trigger · grid · grid-head · week-day · grid-body · week-row · week-number · cell · cell-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-calendar-picker>
Vue components	XhCalendarPickerCell XhCalendarPickerCellTrigger XhCalendarPickerGrid XhCalendarPickerGridBody XhCalendarPickerGridHead XhCalendarPickerHeader XhCalendarPickerHeading XhCalendarPickerHeadingMonthTrigger XhCalendarPickerHeadingYearTrigger XhCalendarPickerNextTrigger XhCalendarPickerNextYearTrigger XhCalendarPickerPrevTrigger XhCalendarPickerPrevYearTrigger XhCalendarPickerRoot XhCalendarPickerWeekDay XhCalendarPickerWeekNumber XhCalendarPickerWeekRow
Composable	useCalendarPicker
State machine	calendarPickerMachine
Skin	@xihan-ui/styles/calendar-picker.css

Events

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

Event	Payload
value-change	CalendarPickerValueChangeDetails
focused-value-change	CalendarFocusChangeDetails
active-view-change	CalendarViewChangeDetails

Slots

Only slots with a payload are listed.

Vue component	Slot	Payload
XhCalendarPickerRoot	default	CalendarPickerRootSlotProps

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
XhCalendarPickerCell	value	string	Yes
XhCalendarPickerCell	index	number
XhCalendarPickerGrid	index	number
XhCalendarPickerHeading	index	number
XhCalendarPickerHeadingMonthTrigger	index	number
XhCalendarPickerHeadingYearTrigger	index	number
XhCalendarPickerRoot	value	string | string[]
XhCalendarPickerRoot	defaultValue	string | string[]
XhCalendarPickerRoot	selectionMode	CalendarPickerSelectionMode
XhCalendarPickerRoot	maxSelected	number
XhCalendarPickerRoot	focusedValue	string
XhCalendarPickerRoot	defaultFocusedValue	string
XhCalendarPickerRoot	min	string
XhCalendarPickerRoot	max	string
XhCalendarPickerRoot	isDateUnavailable	(value: string) => boolean
XhCalendarPickerRoot	invalid	boolean
XhCalendarPickerRoot	locale	string
XhCalendarPickerRoot	firstDayOfWeek	number
XhCalendarPickerRoot	timeZone	string
XhCalendarPickerRoot	disabled	boolean
XhCalendarPickerRoot	readOnly	boolean
XhCalendarPickerRoot	weekdayFormat	CalendarWeekdayFormat
XhCalendarPickerRoot	fixedWeeks	boolean
XhCalendarPickerRoot	granularity	CalendarGranularity
XhCalendarPickerRoot	activeView	CalendarView
XhCalendarPickerRoot	defaultActiveView	CalendarView
XhCalendarPickerRoot	visibleCount	number
XhCalendarPickerRoot	translations	Partial<CalendarPickerTranslations>
XhCalendarPickerRoot	onValueChange	CalendarPickerProps['onValueChange']
XhCalendarPickerRoot	onFocusedValueChange	CalendarPickerProps['onFocusedValueChange']
XhCalendarPickerRoot	onActiveViewChange	CalendarPickerProps['onActiveViewChange']
XhCalendarPickerRoot	children	SlotChildren<CalendarPickerRootSlotProps>
XhCalendarPickerWeekDay	value	number | string	Yes
XhCalendarPickerWeekNumber	value	string	Yes

State

The following names are internal to the state machine.

States: idle

Events: PRESS.START · PRESS.END

Guards: canPress

connect API

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

Member	Type
selectionMode	CalendarPickerSelectionMode
maxSelected	number | null

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
Tab / Shift+Tab	calendar-picker.kbd.tab
ArrowLeft	calendar-picker.kbd.prev-day
ArrowRight	calendar-picker.kbd.next-day
ArrowUp	calendar-picker.kbd.prev-week
ArrowDown	calendar-picker.kbd.next-week
Home	calendar-picker.kbd.week-start
End	calendar-picker.kbd.week-end
PageUp	calendar-picker.kbd.prev-month
PageDown	calendar-picker.kbd.next-month
Shift+PageUp	calendar-picker.kbd.prev-year
Shift+PageDown	calendar-picker.kbd.next-year
Enter / Space	calendar-picker.kbd.select
Enter / Space	calendar-picker.kbd.press

ARIA

These attributes are produced by connect.

Part	Attribute	Value
prev-year-trigger	aria-label	translations.prevYearTrigger(view)
prev-trigger	aria-label	translations.prevTrigger(view)
next-trigger	aria-label	translations.nextTrigger(view)
next-year-trigger	aria-label	translations.nextYearTrigger(view)
grid	aria-disabled	'true' | 'false'
grid	aria-labelledby	frame.headingId(panel.index)
grid	aria-multiselectable	'true' | 'false'
grid	aria-readonly	'true' | 'false'
grid	role	'grid'
grid-head	role	'rowgroup'
week-day	aria-label	meta?.long
week-day	role	'columnheader'
grid-body	role	'rowgroup'
week-row	role	'row'
week-number	aria-hidden	'true'
week-number	role	'rowheader'
cell	aria-selected	'true' | 'false'
cell	role	'gridcell'
cell-trigger	aria-disabled	'true' | 'false'
cell-trigger	aria-label	frame.dateLabel(state.date, state.period)
cell-trigger	role	'button'

Style reference

Skin

@xihan-ui/styles/calendar-picker.css is written against [data-scope="calendar-picker"][data-part="root"] part selectors; the published build uses the mount class .xh-scope-calendar-picker 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
root	data-disabled	'' (present only while the condition holds)
root	data-invalid	'' (present only while the condition holds)
root	data-readonly	'' (present only while the condition holds)
prev-year-trigger	data-disabled	'' (present only while the condition holds)
prev-year-trigger	data-pressed	'' (present only while the condition holds)
prev-year-trigger	data-xh-action-control	''
prev-year-trigger	data-xh-action-display	'always'
prev-year-trigger	data-xh-action-profile	'icon'
prev-year-trigger	data-xh-action-size	'xs'
prev-year-trigger	data-xh-action-variant	'ghost'
prev-trigger	data-disabled	'' (present only while the condition holds)
prev-trigger	data-pressed	'' (present only while the condition holds)
prev-trigger	data-xh-action-control	''
prev-trigger	data-xh-action-display	'always'
prev-trigger	data-xh-action-profile	'icon'
prev-trigger	data-xh-action-size	'xs'
prev-trigger	data-xh-action-variant	'ghost'
next-trigger	data-disabled	'' (present only while the condition holds)
next-trigger	data-pressed	'' (present only while the condition holds)
next-trigger	data-xh-action-control	''
next-trigger	data-xh-action-display	'always'
next-trigger	data-xh-action-profile	'icon'
next-trigger	data-xh-action-size	'xs'
next-trigger	data-xh-action-variant	'ghost'
next-year-trigger	data-disabled	'' (present only while the condition holds)
next-year-trigger	data-pressed	'' (present only while the condition holds)
next-year-trigger	data-xh-action-control	''
next-year-trigger	data-xh-action-display	'always'
next-year-trigger	data-xh-action-profile	'icon'
next-year-trigger	data-xh-action-size	'xs'
next-year-trigger	data-xh-action-variant	'ghost'
heading	data-index	frame.panelOf(panel).index
heading	data-view	view
heading-year-trigger	data-disabled	'' (present only while the condition holds)
heading-year-trigger	data-index	frame.panelOf(panel).index
heading-year-trigger	data-pressed	'' (present only while the condition holds)
heading-year-trigger	data-view	view
heading-year-trigger	data-xh-action-control	''
heading-year-trigger	data-xh-action-display	'always'
heading-year-trigger	data-xh-action-profile	'text'
heading-year-trigger	data-xh-action-size	'xs'
heading-year-trigger	data-xh-action-variant	'ghost'
heading-month-trigger	data-disabled	'' (present only while the condition holds)
heading-month-trigger	data-index	frame.panelOf(panel).index
heading-month-trigger	data-pressed	'' (present only while the condition holds)
heading-month-trigger	data-view	view
heading-month-trigger	data-xh-action-control	''
heading-month-trigger	data-xh-action-display	'always'
heading-month-trigger	data-xh-action-profile	'text'
heading-month-trigger	data-xh-action-size	'xs'
heading-month-trigger	data-xh-action-variant	'ghost'
grid	data-disabled	'' (present only while the condition holds)
grid	data-index	frame.panelOf(panel).index
grid	data-readonly	'' (present only while the condition holds)
grid	data-view	view
week-row	data-view	view
cell	data-disabled	'' (present only while the condition holds)
cell	data-focus	'' (present only while the condition holds)
cell	data-outside-month	'' (present only while the condition holds)
cell	data-selected	'' (present only while the condition holds)
cell	data-today	'' (present only while the condition holds)
cell	data-view	view
cell-trigger	data-disabled	'' (present only while the condition holds)
cell-trigger	data-focus	'' (present only while the condition holds)
cell-trigger	data-outside-month	'' (present only while the condition holds)
cell-trigger	data-pressed	'' (present only while the condition holds)
cell-trigger	data-selected	'' (present only while the condition holds)
cell-trigger	data-today	'' (present only while the condition holds)
cell-trigger	data-view	view
cell-trigger	data-xh-action-control	''
cell-trigger	data-xh-action-display	'always'
cell-trigger	data-xh-action-profile	'text'
cell-trigger	data-xh-action-size	'xs'
cell-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-calendar-picker-cell-bg-disabled	cell	background-color	disabled	--xh-bg-subtle
--xh-calendar-picker-cell-bg-hover	cell-trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-_action-variant-bg-hover
--xh-calendar-picker-cell-bg-pressed	cell-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-bg-pressed
--xh-calendar-picker-cell-bg-selected	cell-trigger	--xh-ink-surface background-color	disabled focus-visible hover loading not([data-disabled]) not([data-loading]) selected xh-ink-surface	--xh-bg-brand
--xh-calendar-picker-cell-bg-selected-active	cell-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed selected	--xh-bg-brand-active
--xh-calendar-picker-cell-bg-selected-disabled	cell-trigger	--xh-ink-surface background-color	disabled selected xh-ink-surface	--xh-bg-subtle-hover
--xh-calendar-picker-cell-fg	cell-trigger	color	@media print default disabled focus-visible hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed selected	--xh-fg-default
--xh-calendar-picker-cell-fg-outside	cell-trigger	color	disabled focus-visible hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) outside-month pressed	--xh-fg-subtle
--xh-calendar-picker-cell-fg-selected	cell-trigger	color	disabled focus-visible hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed selected	--xh-fg-on-brand
--xh-calendar-picker-cell-font-size	cell-trigger	font-size	default	--xh-text-body-size
--xh-calendar-picker-cell-font-weight	cell-trigger	font-weight	default	--xh-font-weight-medium
--xh-calendar-picker-cell-font-weight-outside	cell-trigger	font-weight	outside-month	--xh-font-weight-regular
--xh-calendar-picker-cell-min-w	grid week-row	grid-template-columns min-inline-size	@media (pointer: coarse) default has(> [data-part='week-number']) is([data-view='week'], [data-view='month'], [data-view='quarter'], [data-view='year']) not([hidden]) view=month view=quarter view=week view=year	--xh-control-h-md
--xh-calendar-picker-cell-px	cell	padding-inline	default	--xh-space-0
--xh-calendar-picker-cell-py	cell	inset-block padding-block	default disabled	--xh-space-1_5
--xh-calendar-picker-cell-radius	cell-trigger	border-radius	view=day	--xh-shape-circle
--xh-calendar-picker-cell-size	cell cell-trigger	block-size inline-size inset-block inset-block-start min-inline-size	default disabled today xh-action-profile=icon	--xh-_action-profile-visual-size --xh-control-action-size
--xh-calendar-picker-disabled-inset	cell	inset-block	disabled	--xh-space-0_5
--xh-calendar-picker-gap	root	gap	default	--xh-space-0
--xh-calendar-picker-grid-gap	grid	gap	default	--xh-space-0
--xh-calendar-picker-grid-px	grid week-row	grid-template-columns min-inline-size padding-inline	@media (pointer: coarse) default has(> [data-part='week-number']) is([data-view='week'], [data-view='month'], [data-view='quarter'], [data-view='year']) not([hidden]) view=month view=quarter view=week view=year	--xh-space-4
--xh-calendar-picker-grid-py	grid	padding-block	default	--xh-space-3
--xh-calendar-picker-header-border	header	border-block-end	default	--xh-material-solid-border
--xh-calendar-picker-header-gap	header	gap	default	--xh-space-1
--xh-calendar-picker-header-px	header	padding-inline	default	--xh-space-4
--xh-calendar-picker-header-py	header	min-block-size padding-block	default	--xh-space-2
--xh-calendar-picker-heading-fg	heading heading-month-trigger heading-year-trigger	color	default disabled focus-visible hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) not([hidden]) pressed	--xh-fg-default
--xh-calendar-picker-heading-font-size	heading heading-month-trigger heading-year-trigger	font-size	default not([hidden])	--xh-text-label-size
--xh-calendar-picker-heading-font-weight	heading heading-month-trigger heading-year-trigger	font-weight	default not([hidden])	--xh-font-weight-medium
--xh-calendar-picker-heading-trigger-bg-hover	heading-month-trigger heading-year-trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading]) not([hidden])	--xh-_action-variant-bg-hover
--xh-calendar-picker-heading-trigger-bg-pressed	heading-month-trigger heading-year-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) not([hidden]) pressed	--xh-_action-variant-bg-pressed
--xh-calendar-picker-heading-trigger-px	heading-month-trigger heading-year-trigger	padding-inline	not([hidden])	--xh-space-0_5
--xh-calendar-picker-heading-trigger-radius	heading-month-trigger heading-year-trigger	border-radius	not([hidden])	--xh-shape-control
--xh-calendar-picker-icon-size	header	--xh-icon-size	default	--xh-glyph-size-sm
--xh-calendar-picker-nav-bg	next-trigger next-year-trigger prev-trigger prev-year-trigger	--xh-ink-surface background-color	default focus-visible xh-ink-surface	--xh-_action-variant-bg-focus-visible --xh-_action-variant-bg-rest
--xh-calendar-picker-nav-bg-hover	next-trigger next-year-trigger prev-trigger prev-year-trigger	background-color	disabled hover loading not([data-disabled]) not([data-loading])	--xh-_action-variant-bg-hover
--xh-calendar-picker-nav-bg-pressed	next-trigger next-year-trigger prev-trigger prev-year-trigger	background-color	disabled is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-_action-variant-bg-pressed
--xh-calendar-picker-nav-fg	next-trigger next-year-trigger prev-trigger prev-year-trigger	color	default focus-visible	--xh-fg-muted
--xh-calendar-picker-nav-fg-hover	next-trigger next-year-trigger prev-trigger prev-year-trigger	color	disabled hover is(:active, [data-pressed]) loading not([data-disabled]) not([data-loading]) pressed	--xh-fg-default
--xh-calendar-picker-nav-radius	next-trigger next-year-trigger prev-trigger prev-year-trigger	border-radius	default	--xh-shape-circle
--xh-calendar-picker-nav-size	next-trigger next-year-trigger prev-trigger prev-year-trigger	block-size inline-size min-inline-size	default xh-action-profile=icon	--xh-_action-profile-visual-size
--xh-calendar-picker-period-gap	grid week-row	column-gap gap	is([data-view='month'], [data-view='year']) is([data-view='week'], [data-view='month'], [data-view='quarter'], [data-view='year']) view=month view=quarter view=week view=year	--xh-space-0
--xh-calendar-picker-period-px	cell	padding-inline	is([data-view='week'], [data-view='month'], [data-view='quarter'], [data-view='year']) view=month view=quarter view=week view=year	--xh-space-1
--xh-calendar-picker-period-radius	cell-trigger	border-radius	default	--xh-shape-control
--xh-calendar-picker-row-gap	grid-body grid-head	gap	default	--xh-space-0
--xh-calendar-picker-today-mark-bg	cell	background-color	today	--xh-fg-brand
--xh-calendar-picker-today-mark-size	cell	block-size border inline-size	@media print today	--xh-space-1
--xh-calendar-picker-week-cell-px	cell-trigger	padding-inline	view=week	--xh-space-3
--xh-calendar-picker-week-day-fg	week-day	color	default	--xh-fg-subtle
--xh-calendar-picker-week-day-font-size	week-day	font-size	default	--xh-text-body-size
--xh-calendar-picker-week-day-font-weight	week-day	font-weight	default	--xh-font-weight-regular
--xh-calendar-picker-week-day-h	week-day	block-size	default	--xh-control-h-md
--xh-calendar-picker-week-number-fg	week-number	color	default	--xh-fg-subtle
--xh-calendar-picker-week-number-font-size	week-number	font-size	default	--xh-text-caption-size
--xh-calendar-picker-week-number-w	week-row	grid-template-columns	@media (pointer: coarse) has(> [data-part='week-number']) not([hidden])	--xh-control-h-md
--xh-calendar-picker-year-grid-max-h	grid	max-block-size	view=year	--xh-viewport-h-sm