react-calendar

react-calendar is a lightweight, dependency-light calendar component for React applications, supporting day, month, year, and decade views out of the box. It handles single-date and range selection, locale-aware formatting via the Intl API, and fully customizable navigation, tile content, and styling — without requiring moment.js or any other heavy date library.

Built as a TypeScript-first Yarn workspace monorepo with strict typing, browser-mode Vitest test coverage, and Biome for linting and formatting, react-calendar is maintained by Wojciech Maj and used across thousands of production React apps for date pickers, booking calendars, and scheduling UIs.

What You Get

• Four calendar views (month/year/decade/century) with drill-down and drill-up navigation between them
• Single-date and range selection modes with a configurable returnValue format (start, end, or full range)
• Locale-aware date, weekday, month, and year formatting via the Intl API, with no separate i18n dependency
• A fully typed TypeScript API with per-prop customization for navigation labels, ARIA attributes, and tile content

Common Use Cases

• Booking and reservation UIs that need a start/end date range picker
• Simple date-of-birth or event-date inputs inside forms
• Admin dashboards needing quick year/decade navigation to a specific historical period
• Internationalized products that need locale-correct calendars without bundling a separate date library

Under The Hood

Architecture The root Calendar component (packages/react-calendar/src/Calendar.tsx) is a forwardRef function component that works both controlled and uncontrolled, managing activeStartDate, value, and view via internal useState alongside optional prop overrides, with useImperativeHandle exposing drillDown/drillUp/onChange/setActiveStartDate for ref-based control. It delegates rendering to CenturyView, DecadeView, YearView, or MonthView based on the current view state, each of which composes further into tile/group components (Decade, Year, Navigation, Tile, TileGroup, Flex). Pure date-arithmetic and formatting logic lives in shared/dates.ts, shared/dateFormatter.ts, and shared/utils.ts, keeping view components free of date-math concerns. The repo is a Yarn 4 workspace monorepo with the publishable package under packages/react-calendar and a separate sample/test workspace for manual and automated verification.

Tech Stack Written in TypeScript targeting React 16.8 through 19 as peer dependencies, with a deliberately minimal runtime dependency set — @wojtekmaj/date-utils, clsx, get-user-locale, and warning. The package builds via tsc plus cpy-cli to copy CSS assets into dist, is linted and formatted with Biome 2.5, and is published to npm with provenance enabled. Tests run under Vitest 4 in real-browser mode via @vitest/browser-playwright and vitest-browser-react rather than a DOM-simulation shim, and Husky wires a pre-commit hook into the workflow.

Code Quality Every non-trivial source file — Calendar.tsx, MonthView.tsx, YearView.tsx, DecadeView.tsx, CenturyView.tsx, Navigation.tsx, Decade.tsx, Year.tsx, Flex.tsx, Tile.tsx, and the shared/dates.ts, shared/dateFormatter.ts, and shared/utils.ts utilities — has a matching .spec.tsx/.spec.ts test file, with the Calendar.spec.tsx and shared/dates.spec.ts suites each running over a thousand lines. Invalid states (malformed dates, out-of-range view indices) throw explicit errors rather than failing silently. Biome enforces lint and formatting rules, and a GitHub Actions CI workflow (.github/workflows/ci.yml) runs the pipeline on every change. No CONTRIBUTING guide or dedicated docs directory was found, though the README documents the full prop API in detail.

What Makes It Unique Most React date-picker libraries specialize in a single interaction pattern (day picking, or range picking, or year/decade browsing) and require plugins to cover the rest. react-calendar instead supports all four drill-down granularities — day, month, year, and decade/century — plus first-class range selection in one component, while formatting dates through the native Intl API instead of bundling a full date library like moment.js. The result is a comprehensive calendar feature set with a comparatively small dependency footprint, though the underlying component patterns (controlled/uncontrolled React state, prop-driven customization) are conventional rather than architecturally novel.