react-day-picker

react-day-picker is a React component for building date pickers, calendars, and date inputs. It renders an accessible, headless-friendly calendar grid that supports single, multiple, and range selection modes, along with custom selection logic for more advanced cases. Styling is left entirely to the consumer, whether through plain CSS, CSS Modules, or a utility framework like Tailwind, which is why it underpins the calendar primitives shipped in popular component systems such as shadcn/ui.

The library handles the harder parts of date UI internally: locale-aware formatting and translation via date-fns, ISO 8601 and broadcast week calendars, time zone conversion through @date-fns/tz, and WCAG 2.1 AA keyboard/screen-reader accessibility. Companion @daypicker/* packages extend it with Persian, Hijri, Buddhist, Ethiopic, and Hebrew calendar systems, and every rendered element (day, caption, navigation button, dropdown) can be swapped out with a custom component.

What You Get

• A DayPicker component supporting single, multiple, range, and fully custom selection modes
• Built-in localization and formatting powered by date-fns, including 90+ locale files
• Time zone-aware date handling via the companion @date-fns/tz package
• Support for ISO 8601, broadcast, and (via add-on packages) Persian, Hijri, Buddhist, Ethiopic, and Hebrew calendar systems
• Per-element component overrides (day cells, captions, navigation, dropdowns) for deep visual customization
• WCAG 2.1 AA-compliant keyboard navigation and screen-reader labeling out of the box

Common Use Cases

• Adding a date field or range picker to a booking, scheduling, or reservation form
• Building a custom calendar UI inside a design system, such as the shadcn/ui calendar primitive
• Filtering dashboards or reports by a selected date or date range
• Collecting birthdates, deadlines, or event dates with locale-appropriate formatting
• Building multi-calendar-system date inputs for internationalized products

Under The Hood

Architecture

DayPicker.tsx (packages/react-day-picker/src) is the root component; it composes a DateLib abstraction over date-fns, a useCalendar/useSelection/useFocus hook trio for state, and a getComponents/UI.ts registry so every rendered node (Day, Month, Nav, Dropdown, etc.) is independently overridable, with noonDateLib.ts normalizing dates to noon to avoid DST edge cases.

Tech Stack

TypeScript throughout with strict mode and noUnusedLocals enabled (tsconfig-base.json), date-fns ^4.1.0 and @date-fns/tz ^1.4.1 as the only runtime dependencies, react as a peer dependency (>=16.8.0), built to dual CJS/ESM output via tsc, managed as a pnpm workspace with Changesets for release versioning.

Code Quality

64 test files are colocated under src/ (e.g. DayPicker.test.tsx, useDayPicker.test.tsx, useAnimation.test.tsx, locale.test.ts) and run via Jest with @testing-library/jest-dom custom matchers, plus 111 standalone runnable examples under examples/ that double as integration tests and snapshots; naming is consistent (getX/useX/createX helper conventions) and modules stay small and single-purpose.

API Design

The public API centers on a single DayPicker component with a discriminated mode prop (single/multiple/range/custom) for type-safe selection handling, sensible defaults that let a minimal example render in about six lines, and an extensive docs site (daypicker.dev, sourced from apps/website/docs) covering customization, styling, localization, time zones, and accessibility guides.