Skip to content
flyingsalmon

Date picker

A form field for one calendar day or one range, entered by typing into date segments or by picking from a calendar.

11192026

Installation

npx shadcn@latest add @flyingsalmon/date-picker

Usage

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.

11252026
1222026

Unavailable days

The field holds a Saturday against an isDateDisabled that refuses weekends, so it renders rejected: the invalid ring, the built-in message, and nothing posted.

11212026

Flights leave on weekdays only

That date isn't available

Sizes

Default and small use the same heights as Select, so a date field lines up with its neighbours.

11192026
11192026

Description

Helper text sits under the box and joins the group's accessible description.

11192026

The day you fly out

Error

The app's error wins over the built-in rejection messages.

11192026

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.

mmddyyyy

Pick any day. Mondays are sold out.

Disabled

The whole field leaves the tab order and dims with its label.

11192026

Read-only

The date stays readable and focusable. The clear button is hidden, and the calendar opens for looking only.

11192026

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

  • Do
    Use 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.
  • Do
    Label 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’t
    Let 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’t
    Show 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

KeyDescription
TabMoves 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-9Types into the focused segment.
ArrowUpArrowDownSteps the focused segment.
ArrowLeftArrowRightMoves between segments of the same date.
BackspaceClears the focused segment.
Alt+ArrowDownOpens the panel from anywhere in the box.
EnterSpaceOpens the panel from the calendar button.
EscapeCloses 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.

PropTypeDefaultDescription
modeDatePickerModeDatePickerMode.SingleSingle takes one day. Range takes a pair.
valuestring | DatePickerRange | null–The controlled value: an ISO YYYY-MM-DD day in single mode, { start, end } in range mode, or null.
defaultValuestring | 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.
namestring–Single mode: the name the hidden input posts under.
startName, endNamestring–Range mode: the names the two hidden inputs post under.
labelstring–The visible label. Renders above the box and is wired to it.
labelPlacementFieldLabelPlacementFieldLabelPlacement.AboveAbove the box, or beside it.
sizeDatePickerSizeDatePickerSize.DefaultDefault and Small match the field heights of the same names.
min, maxstring–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.
localestring"en-US"Sets the segment order, the weekday names, and the week start.
descriptionstring–Helper text under the box.
errorstring–The failure message. Turns the border, the ring, and the label destructive. Wins over the built-in ones.
unavailableMessagestring"That date isn't available"Shown when a complete entry fails the limits. Pass a translation.
rangeOrderMessagestring"End date must be after the start date"Shown when a range ends before it starts. Pass a translation.
loadingbooleanfalseReplaces the calendar button with a spinner, blocks opening, and makes the segments read-only.
disabledbooleanfalseTakes the whole field out of the tab order.
readOnlybooleanfalseKeeps the value readable and hides the clear button.
requiredbooleanfalseMarks the label and lets native validation block an empty submit.
sidePanelSidePanelSide.BottomWhich side of the box the panel opens on.
alignPanelAlignPanelAlign.CenterHow the panel aligns to the box.

  • Calendar

    The month grid inside the panel, for use on its own.
  • Fields

    The label, description, error, loading, and disabled behaviour every field shares.
  • Form

    Lays fields out with an actions row and a result slot.
  • Number field

    For a count of days rather than a calendar position.