Skip to main content

​
Overview

Pick a date
April 2026
Date Picker combines an input trigger with a calendar popover. It supports single date selection, date range selection, locale formatting, and min/max date constraints.
For date range selection, use DateRangePicker. Both components share the same API shape — DateRangePicker accepts { from: Date; to?: Date } for its value prop.

​
Installation

​
Usage

​
Variants

​
Single Date (Default)

The default trigger opens a calendar popover for single date selection.
Pick a date

​
With Selected Value

April 1, 2026

​
Date Range Picker

Apr 1, 2026 – Apr 15, 2026

​
Error State

Pick a date
Please select a valid date

​
Disabled

Pick a date

​
API Reference

​
DatePicker

​
Date | undefined
Controlled selected date.
​
(date: Date | undefined) => void
Callback fired when the selected date changes.
​
Date
Uncontrolled default selected date.
​
string
Label displayed above the trigger input.
​
string
default:"Pick a date"
Trigger placeholder text shown when no date is selected.
​
string
default:"PPP"
Date format string (date-fns format). E.g. "dd/MM/yyyy", "MMM d, yyyy".
​
Date
Earliest selectable date. Dates before this are disabled in the calendar.
​
Date
Latest selectable date. Dates after this are disabled in the calendar.
​
boolean
default:"false"
Disables the picker entirely — trigger cannot be opened.
​
string
Helper or error message displayed below the trigger.
​
string
default:"default"
Validation state. Values: default · error
​
string
Additional Tailwind classes for the trigger container.

​
DateRangePicker

Same props as DatePicker, except:
​
{ from: Date; to?: Date } | undefined
Controlled selected date range.
​
(range: { from: Date; to?: Date } | undefined) => void
Callback fired when the selected range changes.

​
Accessibility

  • The trigger renders as a <button> with aria-haspopup="dialog" and aria-expanded
  • The calendar popover uses role="dialog" with aria-modal="true"
  • Individual day cells use role="gridcell" with aria-selected and aria-disabled
  • Keyboard navigation: Arrow keys move focus between days, Enter/Space selects, Escape closes the popover
  • The calendar <table> has role="grid" with column headers labeled by weekday abbreviation

​
Do’s & Don’ts

Do

  • Use minDate and maxDate to constrain valid selections
  • Show the selected date in a human-readable format ("April 1, 2026", not "2026-04-01")
  • Provide a helperText with error state to explain what went wrong
  • Use DateRangePicker for date range inputs — never two separate DatePickers

Don't

  • Don’t use DatePicker for time-only selection — use a time input
  • Don’t disable today’s date unless there’s a valid business reason
  • Don’t rely solely on the calendar for date entry — allow manual text input where possible
  • Don’t use DatePicker inline in dense form rows — it opens a popover that needs space