Guide · Open source

How to use react-dates: install, set up and style a date picker

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

react-dates is an open-source JavaScript library of date-picker components for React web apps. It includes single-date and date-range pickers plus a calendar controller that you add to your own interface. This guide shows how to install it, set it up, wire up a DateRangePicker and customise the look with CSS.

react-datesreact-dates/react-dates · ★ 12.2k · MIT Install options & downloads

Quick start

1Check prerequisites. Make sure Node.js and npm are installed, and that your app uses React and react-dom.
2Install react-dates. Run npm install --save react-dates, or npx install-peerdeps react-dates to add the peer packages too.
3Add the initialise import. Import react-dates/initialize at the top of your application.
4Load the stylesheet. Import react-dates/lib/css/_datepicker.css, or include the resolved file in your HTML head if you do not use Webpack.
5Add a DateRangePicker. Pass startDate, endDate, onDatesChange, focusedInput, onFocusChange and unique ids to the component.
6Override styles. Create a stylesheet after the default one and override classes such as CalendarDay__selected.

What do you need before you install react-dates?

react-dates is built for React. The install process expects Node.js and npm, along with React, react-dom and moment, which are peer packages the library relies on.

The README notes that the library is not meant for projects that do not use React, and that it needs peer packages, so it is not a zero-dependency option.

Node.js and npm
React and react-dom
moment

How do you install react-dates and its peer dependencies?

Install the package with npm. The README also offers a shortcut that installs the peer dependencies automatically. On Windows, use the second command or install the peers by hand, because the first script does not work there.

The shortcut needs npm 5 or higher.

npm install --save react-dates
npx install-peerdeps react-dates

How do you initialise react-dates and load its styles?

Import react-dates/initialize at the top of your application. The README says you cannot import any react-dates components without it, because it sets up class names on the components.

Then load the default stylesheet. With Webpack and a CSS loader, import it directly. Without Webpack, create a CSS file from the path that require.resolve returns for the stylesheet and include it in your HTML head.

The README also says the component assumes box-sizing: border-box is set globally on your page.

Import react-dates/initialize once, near the top of your app.
Import react-dates/lib/css/_datepicker.css with Webpack, or include the resolved file in your HTML head without it.

import 'react-dates/initialize';
import 'react-dates/lib/css/_datepicker.css';

How do you add a DateRangePicker to your app?

DateRangePicker is a fully controlled component. You pass the selected dates through startDate, endDate and onDatesChange, and control focus with focusedInput and onFocusChange. The calendar only shows when focusedInput is defined.

Each picker also needs unique startDateId and endDateId strings. Optional props let you change placeholders, orientation, the number of months shown and more. The live demo and the examples folder in the repository show the options in action.

startDate and endDate take a moment object or null.
onDatesChange fires only when a full date has been entered, even if the user types partial dates.
Set startDateId and endDateId to unique strings on each picker.

<DateRangePicker
  startDate={this.state.startDate}
  startDateId="your_unique_start_date_id"
  endDate={this.state.endDate}
  endDateId="your_unique_end_date_id"
  onDatesChange={({ startDate, endDate }) => this.setState({ startDate, endDate })}
  focusedInput={this.state.focusedInput}
  onFocusChange={focusedInput => this.setState({ focusedInput })}
/>

How do you style the calendar with CSS overrides?

The README's suggested approach is to create a separate stylesheet that overrides the default react-dates styles. Import it after the react-dates styles, because the order of the rules matters.

The example classes include CalendarDay__selected_span for every day in a range, CalendarDay__selected for the start and end dates, and CalendarDay__hovered_span for the days between the cursor and an unselected end date.

CalendarDay__selected_span: styles every selected date in a range.
CalendarDay__selected: styles the start or end date.
CalendarDay__hovered_span: styles days hovered before the end date is chosen.
To change the base class behaviour, the README also describes overriding how PureComponent is used.

.CalendarDay__selected_span {
  background: #82e0aa;
  color: white;
}

Where can you see react-dates working before you commit?

The project has a live demo on its homepage. To run the demo locally, clone the repository, run npm install, then npm run storybook, and visit localhost port 6006.

The Storybook demo lets you try the props before adopting the library, which is useful when you are comparing it with other pickers.

npm install
npm run storybook

What people use it for

Letting users pick a check-in and check-out range in a booking form.
Adding a single-date picker to a form field with SingleDatePicker.
Building a custom calendar layout with DayPickerRangeController.
Showing a date picker in several languages and locales, as the README describes the library as internationalizable.

Frequently asked questions

How do I install react-dates?

Run npm install --save react-dates in your project. The README also suggests npx install-peerdeps react-dates to install the required peer packages automatically, which needs npm 5 or higher.

Is react-dates free to use?

react-dates is released under the MIT licence, as listed in the project details. Check the licence file in the repository before you ship it in a commercial product.

What does react-dates require?

It requires Node.js and npm, React and react-dom, and moment. It is built for React web apps, so it is not suitable for projects that do not use React.

Why is my react-dates date picker not showing up?

The README says the calendar only appears when focusedInput is defined, so check that you pass it and an onFocusChange handler. Also confirm you import react-dates/initialize, because the components will not work without it.

Can I change the colours of the react-dates calendar?

Yes. The README recommends a separate stylesheet that overrides classes such as CalendarDay__selected and CalendarDay__selected_span. Import it after the react-dates styles, since rule order matters.

How does react-dates compare with react-datepicker or react-day-picker?

The project lists react-datepicker, react-day-picker and react-date-range as comparable projects. The source does not benchmark them, so test the Storybook demo or each library's examples against your own needs before choosing.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

react-dates suits React developers who need a date or date-range picker that works in several languages and can be styled with CSS overrides. Skip it if your project does not use React, if you need a zero-dependency solution, or if you require a clearly maintained long-term release, since the README does not state a current version and the last push shown is 2024-04-09.

Install options & downloads