DatePicker

Component for selecting a date with customizable format and placeholder. Built on top of `react-day-picker` (calendar) composed with Base UI `Popover` (positioning + dismiss + a11y). The input/trigger uses our standard input-size and input-font-size design tokens.

function DatePickerExample() {
  const today = new Date();
  const inThreeDays = new Date(new Date().setDate(new Date().getDate() + 3));

  return <DatePicker type="range" defaultValue={[today, inThreeDays]} />;
}

Props

aria-label

Typestring

Accessible name for the trigger button.

aria-labelledby

Typestring

`aria-labelledby` for the trigger button.

className

Typestring

Class name applied to the trigger button.

defaultValue

TypeDate | [Date, Date] | Date[] | string

Initial value when the picker is uncontrolled. - `default` accepts `Date | string` - `range` accepts `[Date, Date]` - `multiple` accepts `Date[]`

disabled

Typeboolean

Disable the picker. The trigger button is not interactive and the popover cannot be opened.

error

Typeboolean

Defaultfalse

Render the trigger in an error state. @default false

id

Typestring

`id` attribute applied to the trigger button.

inputSize

TypeItemSize

Default'medium'

Size variant of the trigger input. @default 'medium'

maxDate

TypeDate

The latest selectable date (inclusive).

minDate

TypeDate

The earliest selectable date (inclusive).

onChange

Typesignature

Callback fired when the selected value changes. - `default` -> the selected `Date` or `null` when cleared - `range` -> `[from, to]` once both dates are selected, otherwise `null` - `multiple`-> the array of selected `Date`s (empty array allowed)

placeholder

Typestring

Default'dd/mm/yyyy'

Placeholder text shown when no date is selected. @default 'dd/mm/yyyy'

readOnly

Typeboolean

Render the picker as read-only. The trigger displays the current value but the popover cannot be opened.

type

Type'default' | 'range' | 'multiple'

Default'default'

Picker type. - `default` selects a single date - `range` selects a `[from, to]` date range - `multiple` selects an arbitrary array of dates @default 'default'

value

TypeDate | [Date, Date] | Date[] | string

Controlled selected value. When set, the picker becomes controlled.

valueFormat

Typestring

Default'DD/MM/YYYY'

Format string used to render the selected date(s) in the trigger. **Note:** This implementation uses `date-fns` format tokens (e.g. `dd/MM/yyyy`). The legacy default value `DD/MM/YYYY` (dayjs tokens) is accepted and converted to the equivalent `date-fns` tokens for backwards compatibility. @default 'DD/MM/YYYY'