Calendar

A date field component that allows users to enter and edit date. Cells grow with the space they get; swipe the grid or use PageUp / PageDown to change months, arrow keys to move between days.

Usage

@Local date: SparkDate | undefined = SparkDates.today();

SCalendar({ selected: this.date!!, bordered: true })

Approximate web preview — the HarmonyOS rendering is the reference.

Multiple

mode: 'multiple' — tap days to toggle them.

@Local days: SparkDate[] = [];

SCalendar({ mode: 'multiple', selectedDates: this.days!!, bordered: true })

Approximate web preview — the HarmonyOS rendering is the reference.

Range

SRangeCalendar shows two months side by side when it is wide enough, otherwise one.

@Local range: SparkDateRange = new SparkDateRange(SparkDates.today(),
  SparkDates.addDays(SparkDates.today(), 6));

// two months side by side when there is room, otherwise one
SRangeCalendar({ range: this.range!!, bordered: true })

Approximate web preview — the HarmonyOS rendering is the reference.

Locale & constraints

locale, weekStartsOn, minDate / maxDate, disabledDates (weekends here) and showOutsideDays.

SCalendar({
  selected: this.date!!,
  locale: 'zh',
  weekStartsOn: 1,
  minDate: SparkDates.today(),
  disabledDates: (d: SparkDate) => SparkDates.weekday(d) === 0 || SparkDates.weekday(d) === 6,
  showOutsideDays: false,
  bordered: true
})

Approximate web preview — the HarmonyOS rendering is the reference.

API

Extracted from the @Param / @Event / @BuilderParam declarations in the library sources.

SCalendar

shadcn-vue Calendar (v4 look, react-day-picker semantics).

• One value prop per mode keeps the types simple: selected (single), selectedDates (multiple), range (range). Each has $name for !! and an on…Change event. Leave them unset to let the calendar keep its own selection.
• month / defaultMonth: the (first) displayed month; onMonthChange reports paging.
• Self-measuring (D11): the cell size follows the width the calendar gets (32–44vp); with numberOfMonths > 1 months sit side by side when they fit and stack otherwise. cellSize pins the cell size.
• Paging: header chevrons, horizontal swipe on the grid, PageUp / PageDown (Shift: year). Arrow keys move the focused day (Home / End: week start / end), Enter / Space pick it.
• Motion key calendar: month changes slide + fade the grid (one container); the selected day always switches instantly.
• weekStartsOn: 1 = Monday (default), 0 = Sunday. locale: 'en' | 'zh' labels.

Prop	Type	Default	Description
mode	SparkCalendarMode SparkCalendarMode = 'single' | 'multiple' | 'range'	'single'
selected!!	SparkDate | undefined	undefined	single mode
selectedDates!!	SparkDate[]	[]	multiple mode
range!!	SparkDateRange	new SparkDateRange()	range mode
month!!	SparkDate | undefined	undefined	Displayed (first) month — any day in it. Controlled when set.
defaultMonth	SparkDate | undefined	undefined	Initially displayed month (default: the selection, else today).
minDate	SparkDate | undefined	undefined
maxDate	SparkDate | undefined	undefined
disabledDates	SparkDateMatcher | undefined	undefined	Extra disabled days, e.g. weekends.
required	boolean	false	single / multiple: tapping the selected day again keeps it (no deselect).
weekStartsOn	SparkWeekStart SparkWeekStart = 0 | 1	1
locale	SparkDateLocale SparkDateLocale = 'en' | 'zh'	'en'
showOutsideDays	boolean	true
numberOfMonths	number	1
cellSize	number | undefined	undefined	Fixed cell size in vp; undefined = adapt to the available width (32–44).
bordered	boolean	false	Card look: rounded-lg border shadow-sm (off inside popovers).

Event	Type	Default	Description
onSelectedChange	(d: SparkDate | undefined) => void	() => { }
onSelectedDatesChange	(d: SparkDate[]) => void	() => { }
onRangeChange	(r: SparkDateRange) => void	() => { }
onMonthChange	(m: SparkDate) => void	() => { }

SRangeCalendar

shadcn-vue RangeCalendar: {@link SCalendar} in range mode that shows two months side by side when its own width allows (≥ 2 × 7 × 36vp + gap + padding), otherwise one.

numberOfMonths pins the month count (undefined = automatic).

Prop	Type	Default	Description
range!!	SparkDateRange	new SparkDateRange()
month!!	SparkDate | undefined	undefined
defaultMonth	SparkDate | undefined	undefined
minDate	SparkDate | undefined	undefined
maxDate	SparkDate | undefined	undefined
disabledDates	SparkDateMatcher | undefined	undefined
weekStartsOn	SparkWeekStart SparkWeekStart = 0 | 1	1
locale	SparkDateLocale SparkDateLocale = 'en' | 'zh'	'en'
showOutsideDays	boolean	true
numberOfMonths	number | undefined	undefined	undefined = 2 when they fit, else 1
cellSize	number | undefined	undefined
bordered	boolean	false

Event	Type	Default	Description
onRangeChange	(r: SparkDateRange) => void	() => { }
onMonthChange	(m: SparkDate) => void	() => { }