DatePicker

Status: Stable
Accessibility: Reviewed
Package: tenet-ui@0.5.0
Source: DatePicker.tsx

import { DatePicker } from 'tenet-ui';

Usage guidelines

When to use: picking a single date from a compact field that opens a calendar on demand (forms, filters). For an always-visible month grid, use Calendar directly (DatePicker wraps it).

Rules

Give it an accessible name via FormControl.Label or aria-label.
Control it with value + onChange, or leave uncontrolled with defaultValue. onChange hands you a real Date.
Constrain with min / max; the popover calendar disables out-of-range days and stops its nav at the boundary.
For form submission pass name — it emits a hidden yyyy-mm-dd input. Use size / fullWidth from the scale (block is the deprecated 0.3.0 name and warns) and invalid for validation state.
Set weekStartsOn={1} and/or locale for non-US conventions; the displayed date and the calendar both follow them.
Never assemble a text input + hand-built dropdown calendar yourself — the popover focus management, the ARIA grid, and the keyboard model are exactly what this composes for you.

Do / Don’t

✅ <DatePicker aria-label="Due date" defaultValue={new Date()} min={new Date()} />
✅ in a form: <FormControl><FormControl.Label>Start date</FormControl.Label><DatePicker name="start" /></FormControl>
❌ <TextInput /> next to a <div> calendar wired by hand — no focus trap-out, no roving grid, no Escape handling.
❌ Storing the value as a formatted string — keep the Date; format only for display.

See also: Calendar (the inline grid it wraps), FormControl; system guideline forms.

Examples

4 stories for DatePicker, open in Storybook

Default components-datepicker--default
With Value components-datepicker--with-value
With Range components-datepicker--with-range
Disabled components-datepicker--disabled

The full matrix (all args, controls, accessibility panel) is in Storybook.

Props

Prop	Type	Default	Description
`value`	`Date \| null`	None	Controlled selected date (null = empty).
`defaultValue`	`Date \| null`	None	Uncontrolled initial selected date.
`onChange`	`(date: Date) => void`	None	Called with the chosen date.
`min`	`Date`	None	Earliest selectable day (inclusive).
`max`	`Date`	None	Latest selectable day (inclusive).
`weekStartsOn`	`WeekStart`	`0`	First day of the week: 0 = Sunday (default), 1 = Monday.
`locale`	`string`	`runtime locale`	BCP-47 locale for the displayed date + calendar. Defaults to the runtime locale.
`placeholder`	`string`	`Select a date…`	Text shown in the trigger when no date is selected.
`size`	`'small' \| 'medium' \| 'large'` DatePickerSize	`medium`	Control height / font scale.
`fullWidth`	`boolean`	None	Stretch the trigger to fill the available width.
`block`deprecated	`boolean`	None	Stretch the trigger to fill the available width. Deprecated since 0.5.0. Use `fullWidth` instead (renamed in 0.4.0). `block` keeps working until 0.6.0.
`invalid`	`boolean`	`false`	Invalid state (danger border + aria-invalid).
`disabled`	`boolean`	`false`	Disable the control.
`required`	`boolean`	`false`	Required (sets aria-required; pairs with FormControl).
`name`	`string`	None	Form field name — emits a hidden input (yyyy-mm-dd) so the value submits with a form.
`id`	`string`	None	Id applied to the trigger (FormControl sets this automatically).
`className`	`string`	None
`aria-label`	`string`	None
`aria-describedby`	`string`	None

Deprecated props keep working for one minor release; the replacement is named in the row.