React DayPicker v10: A Headless Date Picker for React Apps

Who React DayPicker is actually for

Most date pickers make a promise they cannot keep: drop us in and you get a calendar. DayPicker makes a smaller promise. It renders the grid, the weekday headers, the navigation and the selection state, and then stops. Styling is your job, either through plain CSS or a CSS framework, and the README describes the design as minimal for exactly that reason.

That trade is aimed at a specific reader. If your design system already dictates spacing, focus rings and typography, a pre-styled picker means fighting its defaults. DayPicker inverts the cost: you write the CSS once and get a component that matches the rest of your app. The repository ships a long list of example files, from AccessibleDatePicker.tsx to CssModules.tsx and CssVariables.tsx, which suggests styling variations are treated as first-class scenarios rather than edge cases.

The second audience is anyone with calendar requirements that are not Gregorian-only. The README lists add-on packages under the @daypicker/* namespace for Persian, Hijri, Buddhist (Thai), Ethiopic and Hebrew calendars, plus ISO 8601 and broadcast calendars. That is unusual coverage for a React date component, and it is delivered as separate packages rather than baked into the core.

How the component is put together

DayPicker is written in TypeScript and compiled to both CommonJS and ESM, so it works in bundlers that expect either format. It relies on date-fns for date manipulation and formatting rather than shipping its own date arithmetic. That is a deliberate dependency choice: date-fns is a peer in spirit, and the @date-fns/tz package appears in the workspace devDependencies, which lines up with the README's reference to time zone support.

Selection is expressed through a mode prop. The README names single days, multiple days, ranges of days, and custom selections, with custom selections covered by a separate guide. A controlled picker holds the selected value in React state and passes it back through onSelect, as the example in the README shows. The component is also described as compatible with React 16.8 and later, so hooks-era React is the floor, not React 18.

Customization runs on two axes. Props adjust behaviour, and a documented set of customizable components lets you replace rendered elements such as the caption. That second axis is what makes the styling story work: you are not overriding generated class names with !important, you are substituting components.

The repository is a pnpm workspace with apps/, packages/, examples/ and test/ at the top level. The root package.json sets the package manager to [email protected] and requires Node >= 20, and its build script chains a clean, a react-day-picker build and a build of the @daypicker/* packages. If you plan to contribute rather than consume, that is the shape you are entering.

Installing DayPicker and rendering a first picker

The README gives one install command, and it names the preferred package for v10 and newer. Older tutorials that say react-day-picker are describing a previous package name, so check what your lockfile actually resolved before debugging imports.

npm install @daypicker/react

The stylesheet ships with the package and the README imports it from the package root. Without this import the calendar renders as unstyled markup, which is a common first-run surprise.

import { useState } from "react";

import { DayPicker } from "@daypicker/react";
import "@daypicker/react/style.css";

function MyDatePicker() {
  const [selected, setSelected] = useState<Date>();

  return (
    <DayPicker
      mode="single"
      selected={selected}
      onSelect={setSelected}
      footer={
        selected ? `Selected: ${selected.toLocaleDateString()}` : "Pick a day."
      }
    />
  );
}

This is the README's own example. On screen you get a month grid with the current month, and clicking a day updates the footer text through the onSelect callback. The footer prop is a plain React node, so it is a convenient place to confirm that selection state is flowing before you wire the value into a form.

If you need a range instead of a single day, the README points to selection modes in the documentation and the examples directory contains AnimateRange.tsx and ControlledSelection.tsx as working references. The README does not inline the range example, so read those files before guessing at the prop shape.

Where DayPicker will cost you time

The unstyled default is the main friction point. A new team often expects a calendar that looks finished after npm install, and DayPicker does not provide one. You get a stylesheet import, but the README frames styling as something you do with CSS or any CSS framework, and the customization guide is a separate document. Budget for that work explicitly, or you will ship a picker that looks like a wireframe.

The date-fns dependency is the second consideration. It is not optional and it is not hidden. If your bundle already carries a different date library, you now have two, or you migrate. The README states the dependency plainly, but it is easy to miss when evaluating the component on features alone.

Version naming is the third trap. The README says @daypicker/react is preferred for v10 and newer, while recent releases include v10.0.1, v10.0.0 and v8.10.2. That means both package names are live in the wild and a search result can point you at either. Copying an import from an older article without checking your installed version is the fastest way to a module-not-found error.

Finally, DayPicker is a web component for React. The README says nothing about React Native, and the search questions around React Native date pickers are a different problem space. If your target is a native mobile app, this is the wrong tool.

DayPicker against a styled component library

The obvious alternative is a date picker bundled inside a full component library, where the calendar arrives themed and consistent with the rest of the UI kit. The difference is not quality, it is ownership. With a library picker you inherit its design tokens, its update cadence and its opinions about markup. With DayPicker you inherit an unstyled grid and a set of props, and the visual result is whatever your CSS says.

That distinction matters most in two situations. If your product has a design system with its own calendar treatment, a library picker becomes a set of overrides, and overrides age badly across major versions. If your product needs a non-Gregorian calendar, most general-purpose component libraries simply do not cover it, while DayPicker ships named add-on packages for Persian, Hijri, Buddhist, Ethiopic and Hebrew calendars.

The reverse case is equally real. A small internal tool with no design system gains nothing from owning the CSS, and a library picker will get it to a usable screen sooner. DayPicker's advantage only pays out when you actually intend to style it or extend it.

Maintenance, licensing and upgrade cost

The repository is not archived, and the last push was on 2026-08-26, which is recent enough that the project is being touched. The most recent release listed is v10.0.1 from 2026-05-15, with v10.0.0 landing a week earlier on 2026-05-08. The gap between the last push and the last release suggests ongoing work between releases rather than a frozen tree.

Upgrade cost is shaped by the package rename. Moving from the older react-day-picker name to @daypicker/react changes the import specifier and the stylesheet path, so every file that imports the component needs an edit. The repository uses Changesets, visible as the .changeset/ directory and the @changesets/cli devDependency, which means releases are accompanied by changelog entries you can read before upgrading. The root scripts also include a check:versions script and a pack:dry-run script, both of which point at a release process that validates package versions before publishing.

DayPicker is released under the MIT License. That is a permissive licence, and the README links to the licence page at daypicker.dev/license. Read that page and your own legal guidance if licence terms matter to your organisation; nothing here is legal advice. The practical point is that MIT imposes few obligations compared with copyleft alternatives, and the @daypicker/* add-on packages are part of the same repository.

Editorial conclusion

Adopt DayPicker if you need a React calendar whose markup and styling you control, and you are comfortable with date-fns in your dependency tree. Skip it if you want a pre-styled widget or a native mobile date input. Before committing, verify the v10 package name @daypicker/react resolves in your registry, confirm the style.css import path exists in the installed package, and check whether the range mode you need is covered by the selection modes documented at daypicker.dev.

Frequently asked questions

Official sources

1. gpbl/react-day-picker on GitHub
2. License: MIT
3. Project website
4. README
5. Releases