react-datepicker: a React datepicker component with date-fns under the hood

What react-datepicker actually solves

Building a calendar is not hard. Building one that handles keyboard focus, month navigation, locale month names, a time dropdown, and an outside-click handler is a week of work you would rather not repeat in every project. react-datepicker packages that week into a single component: you pass selected and onChange, and it renders the calendar.

The intended user is a React developer filling a form field. The package description calls it "a simple and reusable datepicker component for React", and the API reflects that: the component is controlled, so the parent owns the Date value and the picker only reports changes. There is no internal store, no form library requirement, and no design system attached. If you already use React Hook Form or Formik, the picker is just another controlled input.

It is not a date library. It does not parse, format or convert dates on its own. That job belongs to date-fns, and the README is explicit that the picker "relies on date-fns internationalization to localize its display components".

The mechanism: controlled component plus date-fns locale registry

The data flow is short. The parent holds a Date object in state. DatePicker receives it as selected, renders the month grid for that value, and calls onChange with a new Date when the user clicks a day. Two callbacks exist for different moments: onSelect fires whenever a calendar date is clicked, while onChange fires only when the value has actually changed. If you need to react to every click, including re-selecting the same day, use onSelect.

Localization is a module-level registry, not a prop you can pass raw. You import a locale object from date-fns, hand it to registerLocale with a string key, and then either set it globally with setDefaultLocale or pass the same key to a single instance via the locale prop. getDefaultLocale returns the current global key. This design means locale registration is a side effect on a shared module, so the order of imports matters in server-rendered apps.

The time picker is a prop on the same component. Adding showTimeSelect renders a time list below the calendar, and the README states times are shown at 30-minute intervals by default, configurable through the timeIntervals prop. The dateFormat prop controls the input text; the README example uses dateFormat="Pp", which is a date-fns format token for localized date plus time.

Styling ships as a plain stylesheet, not CSS-in-JS. The package's style field points at dist/react-datepicker.min.css, and the exports map exposes ./dist/ and ./src/stylesheets/. A CSS Modules variant exists at react-datepicker/dist/react-datepicker-cssmodules.css for projects that scope class names.

Installing react-datepicker and rendering a first picker

Install the package from npm. The README also gives the yarn equivalent, yarn add react-datepicker, and notes that React and PropTypes are peer dependencies you must install separately.

npm install react-datepicker --save

The README states you also need to require the CSS file from the package, unless you provide your own stylesheet. The example below is the one the README gives, with a useState hook holding the selected date. After this renders, clicking a day calls onChange with the new Date and the input updates to match.

import React, { useState } from "react";
import DatePicker from "react-datepicker";

import "react-datepicker/dist/react-datepicker.css";

const Example = () => {
  const [startDate, setStartDate] = useState(new Date());
  return <DatePicker selected={startDate} onChange={(date) => setStartDate(date)} />;
};

If your build system scopes CSS, swap the import for the CSS Modules build the README mentions in a comment: react-datepicker/dist/react-datepicker-cssmodules.css. If you need a language other than the default en-US, register a date-fns locale before rendering, then pass its key to the locale prop.

import { registerLocale, setDefaultLocale } from "react-datepicker";
import { es } from "date-fns/locale/es";
registerLocale("es", es);

<DatePicker selected={date} onChange={handleDateChange} locale="es" />

For a time field, add showTimeSelect to the same component. The README's example pairs it with dateFormat="Pp" so the input shows localized date and time together.

The one-day-off problem and other limits

The README devotes a section to timezone handling and the answer is blunt: react-datepicker uses native JavaScript Date objects, dates display in the user's local timezone, and "the library does not include built-in timezone conversion utilities." The frequently reported symptom is a date shifting by one day when you convert to an ISO string or send it to a server. The README attributes this to timezone conversion rather than a bug and links to docs/timezone.md for solutions. For applications that need conversion, it points at date-fns-tz as a companion library.

That is a real constraint, not a footnote. If your domain stores instants (a booking slot, a scheduled job, a deadline shared across regions), you are responsible for the conversion layer, and you should decide where it lives before you write the form.

Browser support is another boundary. The README says the picker targets the latest Chrome, Firefox and IE10+, and that supporting legacy browsers is difficult. React compatibility is version-pinned rather than open-ended: React 16 or newer needs react-datepicker v2.9.4 and above, React 15.5 needs v2.9.3, React 15.4.1 needs v0.40.0, and React 0.13 needs v0.13.0. The README also states it cannot support all older React versions. Check your React version against that table before upgrading the picker.

A smaller friction point: the documentation site examples sometimes import helpers that are not part of the package. The README warns that examples may reference utilities from external libraries, listing date-fns functions and lodash/range, and offers a hand-written range implementation as a substitute. Copying an example without those imports will fail at build time.

How react-datepicker compares with headless calendar libraries

The clearest alternative is a headless calendar primitive such as React DayPicker, which renders the month grid and keyboard behaviour but leaves markup and styling to you. The difference in approach is who owns the visual layer. react-datepicker ships a default stylesheet and a fixed DOM structure, so you get a working calendar in one import and restyle it by overriding its CSS classes or swapping in the CSS Modules build. A headless library gives you no default stylesheet at all, which is more work up front and less fighting later if your design system does not resemble the picker's defaults.

The second axis is the date engine. react-datepicker moved away from Moment.js at v2.0.0 in favour of date-fns and native Date objects, and the README says the switch was made to reduce package size. That choice is why locale registration goes through date-fns objects and why the timezone story is native Date semantics rather than a bundled tz database. A library that keeps its own date abstraction can offer conversion helpers; react-datepicker deliberately does not, and points at date-fns-tz instead.

If your project already standardizes on date-fns, the picker fits without adding a second date library. If your project standardizes on something else, you are introducing date-fns as a dependency for localization alone.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-04-02. The most recent release listed is v9.1.0 on 2025-12-19, following v9.0.0 on 2025-12-08 and v8.10.0 on 2025-11-26. That cadence suggests a maintained project, though the README does not document a deprecation policy or a support window for older major versions.

Upgrade cost is concentrated in two places. First, the React compatibility table: the README ties picker versions to specific React versions, so a React upgrade can force a picker upgrade. Second, the stylesheet. Because the package ships CSS at react-datepicker/dist/react-datepicker.css and marks CSS files as side effects in package.json, tree-shaking will not remove it, and any class-name changes between majors land in your override rules. The README does not document rollback or downgrade steps, so pin your version in package.json rather than relying on a caret range during a major upgrade.

The licence is MIT, declared in both the README badge and the package.json license field. MIT permits commercial and closed-source use and requires preserving the copyright notice and licence text. That is a general description of the licence, not legal advice; check the LICENSE file in the repository for the binding terms.

Editorial conclusion

Adopt react-datepicker if you want a prop-driven calendar inside an existing React form and you are willing to import its stylesheet and register a date-fns locale yourself. Skip it if your dates are stored as timezone-sensitive instants, because the README states the library ships no timezone conversion utilities, or if you need a headless component you style entirely from scratch. Before committing, check that your React version matches the compatibility table in the README, confirm your bundler can import react-datepicker/dist/react-datepicker.css, and read docs/timezone.md for the one-day-off case.

Frequently asked questions

Official sources

1. Hacker0x01/react-datepicker on GitHub
2. License: MIT
3. Project website
4. README
5. Releases