Date Picker

A field that opens a Calendar to choose a single date.

import { DatePicker } 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 { DatePicker } from '@basiiik/ui';

<DatePicker label="Due date" />

Example values were filled in for the required prop label: replace them with your own.
Hover and Focused are CSS. Open is open / defaultOpen. Error is the error prop (or an unreadable typed date). Disabled uses the disabled attribute. Filled is a non-empty value. Needs label or aria-label.
Compose with: calendar, calendar-day, icon-button.
Storybook: Inputs/Date Picker.

Props

Prop	Type	Notes
`size`	`"sm" \| "md"`	Default "md"
`label`	`ReactNode`
`helperText`	`ReactNode`
`placeholder`	native attribute
`error`	`ReactNode`
`disabled`	native attribute
`open`	`boolean`
`aria-label`	`string`
`aria-labelledby`	`string`

Other props

Prop	Type	What it does
`name`	`string`	Name for a form: submits the date as `YYYY-MM-DD`.
`value`	`Date \| null`	The chosen date (controlled). `null` is empty.
`defaultValue`	`Date \| null`
`onValueChange`	`(date: Date \| null) => void`
`min`	`Date`
`max`	`Date`
`isDateDisabled`	`(date: Date) => boolean`
`locale`	`string`	BCP 47 locale for names and the typed format. Defaults to the browser's.
`weekStartsOn`	`WeekStart`
`today`	`Date`	Today's date. Pass one for deterministic tests and stories.
`defaultOpen`	`boolean`
`onOpenChange`	`(open: boolean) => void`
`chooseLabel`	`string`	Accessible name of the calendar button and dialog.

States. Hover and Focused are CSS. Open is open / defaultOpen. Error is the error prop (or an unreadable typed date). Disabled uses the disabled attribute. Filled is a non-empty value. Needs label or aria-label.

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

Use it when

Choosing one date near today such as a booking or due date

Do not use it when

Free-form text (use Text Field)
Dates far in the past or future where typing is faster (offer the field alone)
Date ranges (not supported yet)

Rules for agents

Every Date Picker has a visible label
Typing a date must always work; never make the calendar the only way to enter a date
Show the expected format in helperText or the placeholder, for the locale in use
Limit choices with min, max and isDateDisabled instead of rejecting dates after the fact
Pass locale when the page language differs from the browser default

Avoid

Making the field read-only so people must use the calendar
Using a Date Picker for a birth date or other date far from today (use the typed field alone)
Faking a date range with two pickers and no validation between them (ranges are not supported yet)
Hard-coding a date format instead of using the locale prop

Writing the content

Labels name the date: 'Due date', 'Check-in'
Helper text shows the format: 'DD/MM/YYYY'
Use sentence case

Keyboard

Type a date directly in the field
Enter, Space or ArrowDown on the button opens the calendar
Escape closes and returns focus to the button
Selecting a day closes the calendar and fills the field

Accessibility

Button: aria-haspopup="dialog", aria-expanded, and a name such as "Choose date"
Calendar popover: role="dialog" with an accessible name
aria-invalid and aria-describedby for Error and helper text

Colour tokens it reads

color.bg.brand.defaultcolor.bg.disabledcolor.bg.surfacecolor.border.brandcolor.border.dangercolor.border.focuscolor.border.inputcolor.border.subtlecolor.icon.primarycolor.text.brandcolor.text.dangercolor.text.disabledcolor.text.on-brandcolor.text.primarycolor.text.secondarycolor.text.tertiary

inputs 12 Figma variants Try it in the live demo