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

npm install @araf-ds/core

​
Usage

import { DatePicker, DateRangePicker } from "@araf-ds/core"

export default function Example() {
  return (
    <DatePicker
      label="Start date"
      placeholder="Pick a date"
    />
  )
}

​
Variants

​
Single Date (Default)

The default trigger opens a calendar popover for single date selection.
Pick a date
<DatePicker label="Start date" placeholder="Select start date" />

​
With Selected Value

April 1, 2026
<DatePicker
  label="Date of birth"
  value={date}
  onValueChange={setDate}
  maxDate={new Date()}
/>

​
Date Range Picker

Apr 1, 2026 – Apr 15, 2026
<DateRangePicker
  label="Booking period"
  placeholder="Select date range"
/>

​
Error State

Pick a date
Please select a valid date
<DatePicker
  label="Expiry date"
  state="error"
  helperText="Please select a valid date"
/>

​
Disabled

Pick a date
<DatePicker label="Delivery date" disabled />

​
API Reference

​
DatePicker

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

​
DateRangePicker

Same props as DatePicker, except:
​
value
{ from: Date; to?: Date } | undefined
Controlled selected date range.
​
onValueChange
(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