DatePicker

Alpha

An accessible date picker with calendar grid navigation, single and range selection modes, and keyboard-first design following the ARIA date picker pattern.

Import

import { DatePicker } from "@compa11y/react";

Usage

Example.tsx
import { useState } from "react";
import { DatePicker, Button, Text } from "@compa11y/react";

// Single date
function BirthdayPicker() {
  const [date, setDate] = useState<Date>();

  return (
    <div>
      <Text as="label" size="sm" weight="semibold">Birthday</Text>
      <DatePicker value={date} onValueChange={setDate}>
        <DatePicker.Input placeholder="DD/MM/YYYY" />
        <DatePicker.Trigger>
          <Button variant="ghost" size="sm">Pick date</Button>
        </DatePicker.Trigger>
        <DatePicker.Calendar />
      </DatePicker>
    </div>
  );
}

// Date range
function BookingDateRange() {
  const [range, setRange] = useState<[Date, Date]>();

  return (
    <DatePicker
      mode="range"
      value={range}
      onValueChange={setRange}
      minDate={new Date()}
    >
      <DatePicker.RangeInputs />
      <DatePicker.Calendar />
    </DatePicker>
  );
}

Features

  • Single date and date range selection
  • Full keyboard navigation in calendar grid
  • Day, month, and year precision views
  • Popover or modal overlay modes
  • Min/max date constraints
  • Screen reader announcements for date changes
  • Compound component API

Props

DatePicker component props
PropTypeDefaultDescription
valueDate | [Date, Date]-Controlled value (single Date or [start, end] range)
onValueChange(value: Date | [Date, Date]) => void-Called when date selection changes
mode'single' | 'range''single'Selection mode
precision'day' | 'month' | 'year''day'Calendar precision
overlay'popover' | 'modal''popover'Overlay type
minDateDate-Earliest selectable date
maxDateDate-Latest selectable date
disabledbooleanfalseDisables the date picker

Sub-components

DatePicker.Input

DatePicker.Input props
PropTypeDefaultDescription
placeholderstring-Input placeholder

DatePicker.Trigger

DatePicker.Trigger props
PropTypeDefaultDescription
childrenReactNode-Calendar icon button

DatePicker.Calendar

Keyboard Interactions

Accessibility
All keyboard interactions follow WAI-ARIA best practices and work without any additional configuration.
Keyboard shortcuts for DatePicker
KeyAction
ArrowLeft / ArrowRightMove to previous/next day
ArrowUp / ArrowDownMove to same day in previous/next week
Home / EndMove to first/last day of the week
PageUp / PageDownMove to same day in previous/next month
Enter / SpaceSelect the focused date
EscapeClose the calendar overlay