Forms
Date Picker
Date Picker is a date-only field with editable D MMM YYYY text entry (en-GB) and calendar popover for single-date selection.
State × Size — 5 variants
betaReact AvailableFigma AvailableDocs Partial
- React last updated
- 2026-07-13
- Documentation last updated
- 2026-06-01
- Accessibility target
- WCAG 2.2 AA (target)
- Version
- 0.5.0-beta
Known open questions
- Custom formatDate/parseDate pairs override locale display when both are provided.
Purpose
Text-input-style entry for a calendar date, intended to trigger a calendar popover for visual date selection.
Anatomy
Date Picker composes FormField + editable text input + calendar button + Popover + Calendar Grid + hidden YYYY-MM-DD input.
Variants and states
single-date
When to use
Any date-entry field where a calendar picker aids accuracy over free-typing.
When not to use
When only a rough date/timeframe matters.
Accessibility
The calendar icon should trigger the same popover as clicking the input itself; both need to be keyboard operable.
Keyboard behavior
Calendar button opens the popover. Text field accepts D MMM YYYY entry (blur/Enter to commit). Calendar Grid handles day navigation. Escape closes and restores trigger focus.
Common mistakes
Assuming this component includes the calendar grid — pair it with Content/Calendar for the full picker.
Properties
State × Size as variants. Value (text, formatted date string).
Should Date Picker allow direct text entry?
Yes — the text field accepts D MMM YYYY (en-GB only, e.g. 11 Jul 2026). Invalid, out-of-range, or disabled dates show a visible validation error. Numeric regional formats are not accepted.
How is the selected date submitted in a form?
A hidden input submits canonical YYYY-MM-DD. Display text is not submitted.
What is the difference between Date Picker and Calendar Grid?
Calendar Grid is the month selection surface. Date Picker wraps it in a labelled field with popover trigger behavior.
How does Date Picker avoid time-zone date shifts?
Values are stored and submitted as date-only YYYY-MM-DD strings using local calendar arithmetic — never UTC midnight conversion.
Tokens used
component/radius/controlsemantic/border/defaultsemantic/icon/muted
Component API
| Prop | Type | Default | Description |
|---|---|---|---|
| label | string | — | Field label via FormField. |
| value | YYYY-MM-DD | — | Controlled selected date. |
| defaultValue | YYYY-MM-DD | — | Initial selected date. |
| onValueChange | (date) => void | — | Selection callback. |
| name | string | — | Hidden input name for form submission. |
| required | boolean | — | Required field indicator. |
| disabled | boolean | — | Prevents opening and submission. |
| readOnly | boolean | — | Prevents editing and opening while remaining perceivable. |
| error | string | — | Validation message via FormField. |
| minDate | YYYY-MM-DD | — | Earliest selectable date, inclusive. |
| maxDate | YYYY-MM-DD | — | Latest selectable date, inclusive. |
| isDateDisabled | (date) => boolean | — | Additional disabled-date predicate. |
React example
Copy React example
import { DatePicker } from "@/components/ui/DatePicker";
export function Example() {
return (
<DatePicker
label="Release date"
name="release-date"
defaultValue="2026-07-11"
/>
);
}