Date picker
A form field for one calendar day or one range, entered by typing into date segments or by picking from a calendar.
Installation
npx shadcn@latest add @flyingsalmon/date-pickerUsage
import { useState } from 'react'
import { DatePicker } from '@/components/ui/date-picker'
export function DatePickerUsage() {
const [departure, setDeparture] = useState<string | null>(null)
return (
<DatePicker label="Departure" value={departure} onChange={setDeparture} />
)
}Examples
A range
mode={DatePickerMode.Range} takes a { start, end } pair. Both groups of segments share one box, one label, and one error message. Picking the end day commits and closes the panel; Escape mid-range leaves the committed range in place.
Sizes
Default and small use the same heights as Select, so a date field lines up with its neighbours.
Description
Helper text sits under the box and joins the group's accessible description.
The day you fly out
Error
The app's error wins over the built-in rejection messages.
That flight is sold out
Loading
Pick a day. The calendar button becomes a spinner while the flight check runs, and Monday fails into the field's own error.
Pick any day. Mondays are sold out.
Disabled
The whole field leaves the tab order and dims with its label.
Read-only
The date stays readable and focusable. The clear button is hidden, and the calendar opens for looking only.
Guidelines
When to use
- To pick a departure day or a trip range, where the traveller may type a date or browse a month.
- In any form that posts a date, because a plain form submits it.
When not to use
- Use Calendar when the calendar itself is the interface, on a page or in a card rather than behind a field.
- Use Input for a code that only looks like a date, such as a booking reference.
- Use Number field for a count of days rather than a position on the calendar.
Do and don’t
- DoUse a range for a trip and a single day for moving one date.A range picks both ends in one panel across two months, so the trip reads as a span. Moving one booking needs no second end to ignore.
- DoLabel the field with the question, such as "When" or "New date", never with the control’s name.The segments already show it is a date. The label says what the date is for.
- Don’tLet the traveller pick a day the trip cannot use and refuse it on submit.Bound the field from the trip itself, such as today onwards. Refused days are struck through in the grid and rejected as they are typed, so no error arrives after the traveller thinks they are done.
- Don’tShow an error while a date is still being typed.A half-typed date is not wrong yet. The field stays silent until every segment is filled, and only then says whether the day is available.
Accessibility
| Key | Description |
|---|---|
| Tab | Moves through each segment, then the clear button when it is shown, then the calendar button. In a range, Tab is also the way from the start group to the end group. |
| 0-9 | Types into the focused segment. |
| ArrowUpArrowDown | Steps the focused segment. |
| ArrowLeftArrowRight | Moves between segments of the same date. |
| Backspace | Clears the focused segment. |
| Alt+ArrowDown | Opens the panel from anywhere in the box. |
| EnterSpace | Opens the panel from the calendar button. |
| Escape | Closes the panel and returns focus to whatever opened it. |
Inside the panel, the keys are those of Calendar. Screen readers hear the group name, then “Start date” and “End date” in a range, then each segment. A partly typed entry is silent: no ring, no message, and no onChange. A complete entry the limits refuse takes aria-invalid and shows the built-in message, and nothing is posted, so a form cannot submit a value the field refused. A loading field sets aria-busy. The states every field shares are described on Fields.
API
DatePicker
mode selects the value shape, and the value, handler, and name props follow it. className styles the wrapper.
| Prop | Type | Default | Description |
|---|---|---|---|
| mode | DatePickerMode | DatePickerMode.Single | Single takes one day. Range takes a pair. |
| value | string | DatePickerRange | null | – | The controlled value: an ISO YYYY-MM-DD day in single mode, { start, end } in range mode, or null. |
| defaultValue | string | DatePickerRange | null | – | The initial value of an uncontrolled field, in the same shape as value. |
| onChange | (value) => void | – | Fires with ISO YYYY-MM-DD days when the value changes to a complete, accepted entry, or with null when cleared. A partly typed entry never reaches it. |
| name | string | – | Single mode: the name the hidden input posts under. |
| startName, endName | string | – | Range mode: the names the two hidden inputs post under. |
| label | string | – | The visible label. Renders above the box and is wired to it. |
| labelPlacement | FieldLabelPlacement | FieldLabelPlacement.Above | Above the box, or beside it. |
| size | DatePickerSize | DatePickerSize.Default | Default and Small match the field heights of the same names. |
| min, max | string | – | ISO YYYY-MM-DD bounds for the segments and the grid. Set them instead of validating afterwards: an earlier day is refused in the panel and rejected when typed. |
| isDateDisabled | (date: string) => boolean | – | Refuses days the traveller cannot pick. They stay reachable by arrow key but cannot be chosen. |
| locale | string | "en-US" | Sets the segment order, the weekday names, and the week start. |
| description | string | – | Helper text under the box. |
| error | string | – | The failure message. Turns the border, the ring, and the label destructive. Wins over the built-in ones. |
| unavailableMessage | string | "That date isn't available" | Shown when a complete entry fails the limits. Pass a translation. |
| rangeOrderMessage | string | "End date must be after the start date" | Shown when a range ends before it starts. Pass a translation. |
| loading | boolean | false | Replaces the calendar button with a spinner, blocks opening, and makes the segments read-only. |
| disabled | boolean | false | Takes the whole field out of the tab order. |
| readOnly | boolean | false | Keeps the value readable and hides the clear button. |
| required | boolean | false | Marks the label and lets native validation block an empty submit. |
| side | PanelSide | PanelSide.Bottom | Which side of the box the panel opens on. |
| align | PanelAlign | PanelAlign.Center | How the panel aligns to the box. |