Components / inputs

Calendar

A month grid for picking a single date. Header has previous and next month buttons; the grid is a Sunday-first week layout.

import { Calendar } from '@basiiik/ui';

The snippet an agent gets

From get_component_snippet, with the required props filled in from the spec. Every snippet is type-checked against the library before it is shipped.

import { Calendar } from '@basiiik/ui';

<Calendar />

Controlled with value and onValueChange (and month), or uncontrolled with defaultValue. Constrain with min, max and isDateDisabled; locale and weekStartsOn set names and week layout.
Compose with: calendar-day, icon-button.
Storybook: Inputs/Calendar.

Props

Prop	Type	Notes
`size`	`"sm" \| "md"`	Default "md"

Other props

Prop	Type	What it does
`value`	`Date \| null`	The chosen date (controlled).
`defaultValue`	`Date \| null`
`onValueChange`	`(date: Date) => void`
`month`	`Date`	The visible month (controlled). Any date inside it.
`defaultMonth`	`Date`
`onMonthChange`	`(month: Date) => void`
`min`	`Date`
`max`	`Date`
`isDateDisabled`	`(date: Date) => boolean`
`locale`	`string`	BCP 47 locale for month, weekday and date names. Defaults to the browser's.
`weekStartsOn`	`WeekStart`	First day of the week: 0 is Sunday. Default 0.
`today`	`Date`	Today's date. Pass one for deterministic tests and stories.
`autoFocus`	`boolean`	Move keyboard focus to the current day on mount, for use inside a popup.

States. Controlled with value and onValueChange (and month), or uncontrolled with defaultValue. Constrain with min, max and isDateDisabled; locale and weekStartsOn set names and week layout.

Native attributes such as className, id and data-* are forwarded to the root element.

Use it when

Inline date selection, or as the popover of a Date Picker

Do not use it when

Choosing a far-away date such as a birth year (offer typing in a Date Picker)
Selecting a range (not supported yet)

Rules for agents

Control it with value and onValueChange; use month and onMonthChange only when the visible month must be controlled
Limit choices with min, max and isDateDisabled
Pass locale and weekStartsOn for the audience; dates are formatted with Intl
Use autoFocus when the Calendar opens in a popup so keyboard focus lands on the current day
For a date field people can type into, use Date Picker, which wraps Calendar

Avoid

A Calendar for a birth date or other far-away date (use Date Picker and let people type)
Faking range selection with two Calendars (ranges are not supported yet)
Hard-coding a week start or month names instead of using locale and weekStartsOn
Disabling dates without explaining the rule nearby

Keyboard

Arrow keys move by day and week
PageUp and PageDown change month; Shift+PageUp and Shift+PageDown change year
Home and End go to the start and end of the week
Enter and Space select; only one day is in the Tab order (roving tabindex)

Accessibility

aria-label or aria-labelledby names the grid with the month and year
Previous and next buttons are named "Previous month" and "Next month"
Month changes are announced with aria-live="polite"

Colour tokens it reads

color.bg.brand.defaultcolor.bg.surfacecolor.border.brandcolor.border.subtlecolor.text.brandcolor.text.disabledcolor.text.on-brandcolor.text.primarycolor.text.tertiary

inputs 2 Figma variants Try it in the live demo