DatePicker

React DatePicker components are used to select a single date from a calendar. They are commonly used in forms, filters, booking flows, and scheduling features.

This DatePicker component is built with React Aria Components and styled using Tailwind CSS. It supports date selection with keyboard-friendly interaction.

Installation

The Date Picker relies on @internationalized/date for date manipulation.

npx @tailgrids/cli add date-picker

Usage

The following example demonstrates how to use the DatePicker compound components.

import {
  DatePicker,
  DatePickerGroup,
  DatePickerPopover,
  DatePickerTrigger
} from "@/registry/core/date-picker";
import { DateInput, DateSegment } from "@/registry/core/date-field";
import { CalendarDate, getLocalTimeZone, today } from "@internationalized/date";
import { useState } from "react";

export default function DatePickerUsage() {
  const [date, setDate] = useState<CalendarDate | null>(
    today(getLocalTimeZone())
  );

  return (
    <DatePicker value={date} onChange={setDate}>
      <DatePickerGroup>
        <DateInput>{segment => <DateSegment segment={segment} />}</DateInput>
        <DatePickerTrigger />
      </DatePickerGroup>
      <DatePickerPopover />
    </DatePicker>
  );
}

Examples

Basic Usage

A simple date picker with a label and helper description. The popover opens when clicking the calendar icon.

Controlled

Manage the date value externally using value and onChange props.

Uncontrolled

An uncontrolled DatePicker with a default value.

Disabled

Use disabled prop to disable the DatePicker.

With Date Constraints

Restrict date selection to a valid range using minValue and maxValue.

With Date and Time

Combine date and time by using a CalendarDateTime value. Set granularity other then "day" to expose time segments.

Validation

A DatePicker with custom validation that rejects weekend selections using the validate prop.

Service Booking

A DatePicker for selecting a service date, followed by a time slot picker that appears after a date is chosen.

Availability Indicators

A DatePicker that uses isDateUnavailable to mark weekend dates as unavailable, with a legend inside the popover footer showing available and unavailable indicators.

Weekday Only

A DatePicker restricted to weekdays only using isWeekday from @internationalized/date. Useful for scheduling business appointments and professional meetings.

Delivery Date Estimate

A DatePicker with a 3-day minimum notice period and shipping speed selection (Standard or Express) that estimates the arrival date.

International Calendar

Wrap the DatePicker with an I18nProvider and set the locale prop to use a different calendar system.

API Reference

DatePicker (Root)

The root component that wraps react-aria-components DatePicker. Accepts all AriaDatePickerProps with renamed boolean props.

DatePickerGroup

A styled wrapper that groups the input and trigger button. Wraps react-aria-components Group.

DatePickerTrigger

Renders the calendar trigger button. Wraps react-aria-components Button.

DatePickerPopover

Renders the calendar popover. Wraps react-aria-components Popover.

Composition

The Date Picker is composed of the root DatePicker component plus DatePickerGroup, DatePickerTrigger, and DatePickerPopover. It can be combined with shared field components (FieldLabel, FieldDescription, FieldError) for a complete form control.

DatePicker                                                  — Root container. Manages date state, popover open state, and ARIA context.
├── FieldLabel                                              — Visible label.
├── DatePickerGroup                                         — Groups the date input and trigger button.
│   ├── DateInput                                           — Wraps editable segments in a styled input area.
│   │   └── DateSegment                                     — Individual editable segment (day, month, year).
│   └── DatePickerTrigger                                   — Calendar icon button that opens the popover.
└── DatePickerPopover                                       — Floating popover containing the calendar.
    └── Calendar                                            — The calendar grid for date selection.
        ├── CalendarHeader                                  — Month/year navigation row.
        │   ├── NavButton (previous)                        — Previous month button.
        │   ├── CalendarHeading                             — Current month/year label.
        │   └── NavButton (next)                            — Next month button.
        ├── CalendarGrid                                    — The week grid container.
        │   ├── CalendarGridHeader                          — Day-of-week header row.
        │   └── CalendarGridBody                            — Date cell rows.
        │       └── CalendarCell                            — Individual date cell.

• Use DatePicker as the root. It provides the date value, validation state, and popover open state to all children.
• Use FieldLabel to label the field. Pair it with aria-labelledby for accessibility.
• Use DatePickerGroup to wrap the DateInput and DatePickerTrigger.
• Use DateInput to render the segment group. It accepts a render function that receives each segment and returns a DateSegment.
• Use DateSegment inside DateInput to render each editable part of the date. It handles focus, typing, and arrow-key incrementing.
• Use DatePickerTrigger for the calendar icon button that opens the popover.
• Use DatePickerPopover as the floating container for the calendar.
• Use Calendar and its sub-components inside the popover to render the date selection grid.
• Use FieldDescription for helper text. It is automatically announced by screen readers.
• Use FieldError for validation messages. It is linked via aria-errormessage when invalid is set.

Accessibility

• All buttons and calendar controls are keyboard accessible
• Month navigation buttons support keyboard interaction
• Uses standard <button> elements for all interactive controls
• Focus is managed to allow closing the calendar without mouse input
• Built on react-aria-components which follows WAI-ARIA authoring practices
• Date segments are individually editable and accessible via keyboard
• Validation errors are announced to screen readers via aria-describedby