React Dates

21.8.0 · maintenance · verified Tue Apr 21

React Dates is a robust and accessible date range picker component library for React, developed and maintained by Airbnb. It offers highly customizable single and range date pickers, including features like internationalization, mobile responsiveness, and full accessibility support. The current stable version is 21.8.0. The library relies on `moment` for all date handling, which is a significant architectural decision as `moment` is now in maintenance mode. Since v13.0.0, it mandates an explicit initialization import (`react-dates/initialize`) to set up its underlying `react-with-styles` styling solution, and it assumes `box-sizing: border-box` is globally applied for correct layout. Its release cadence has slowed, with the last npm publication over six years ago, suggesting it's in a maintenance phase rather than active feature development, though still widely used.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'call') / Component does not render / Styles missing
```
cause The required `react-dates/initialize` side-effect import was omitted, preventing `react-with-styles` from correctly setting up component styles.

fix Add `import 'react-dates/initialize';` to the top of your application's main entry file (e.g., `index.js`).
```
Date picker displays without any styling (plain HTML elements)
```
cause The default `_datepicker.css` stylesheet was not imported or was imported incorrectly, leading to unstyled components.

fix Ensure you have `import 'react-dates/lib/css/_datepicker.css';` in your component or main application file, and that your build setup correctly handles CSS imports.
```
Module not found: Can't resolve 'moment' in '...' during build or runtime
```
cause The `moment` library, a peer dependency of `react-dates`, has not been installed.

fix Install `moment` using `npm install moment` or `yarn add moment`.
```
Warning: Failed prop type: The prop `startDateId` is marked as required in `DateRangePicker`, but its value is `undefined`.
```
cause Essential props like `startDateId`, `endDateId`, `focusedInput`, and handlers (`onDatesChange`, `onFocusChange`) are missing or incorrectly passed to `DateRangePicker` or `SingleDatePicker`.

fix Provide all required props to the `DateRangePicker` or `SingleDatePicker` component, ensuring unique `id`s for `startDateId` and `endDateId`.

Warnings

breaking Since v13.0.0, `react-dates` requires an explicit `import 'react-dates/initialize';` statement at the top of your application's entry point. Failure to include this will result in unstyled components or runtime errors, as it sets up the necessary `react-with-styles` context.
Fix: Add `import 'react-dates/initialize';` to your application's main entry file (e.g., `index.js` or `App.js`) before any other `react-dates` component imports.
gotcha The component assumes that `box-sizing: border-box` is set globally in your page's CSS. Without this, the layout and sizing of the date picker elements may render incorrectly, leading to visual distortions or overflows.
Fix: Ensure your global CSS includes rules like `html { box-sizing: border-box; } *, *::before, *::after { box-sizing: inherit; }` to apply `border-box` consistently.
gotcha `react-dates` has a critical peer dependency on `moment`. While `moment` is installed in most existing projects, its development ecosystem is in maintenance mode. New projects might prefer modern alternatives like `date-fns` or `luxon`, but `react-dates` is tightly coupled to `moment` and does not offer alternatives.
Fix: Install `moment` as a direct dependency (`npm install moment` or `yarn add moment`) alongside `react-dates`. Be aware of the long-term implications of relying on `moment` for new application development.
gotcha When overriding the default `react-dates` styles, the order of your CSS imports is crucial. Your custom stylesheet *must* be imported after `react-dates/lib/css/_datepicker.css` to ensure your overrides take precedence due to CSS specificity rules.
Fix: In your component or application entry file, ensure `import 'react-dates/lib/css/_datepicker.css';` appears before `import './your-custom-styles.css';`.

Install

npm install react-dates npm
yarn add react-dates yarn
pnpm add react-dates pnpm

Imports

DateRangePicker, SingleDatePicker, DayPickerRangeController
wrong:
```
import DateRangePicker from 'react-dates'; // Incorrect: these are named exports
```
correct:
```
import { DateRangePicker, SingleDatePicker, DayPickerRangeController } from 'react-dates';
```
These are named exports for the primary picker components. Most applications will use `DateRangePicker` or `SingleDatePicker`.
Initialize styling
wrong:
```
import { initialize } from 'react-dates/initialize'; // Incorrect: this is a side-effect import
```
correct:
```
import 'react-dates/initialize';
```
Required since v13.0.0 to configure styling with `react-with-styles`. This must be imported once at the top level of your application before any `react-dates` components are rendered.
Default CSS styles
```
import 'react-dates/lib/css/_datepicker.css';
```
Imports the default stylesheet. Requires a CSS loader (e.g., Webpack's `css-loader`). This import should generally come before any custom override stylesheets.

Quickstart

This quickstart demonstrates the basic setup and usage of the `DateRangePicker` component from `react-dates`. It includes the necessary global initialization and CSS imports, manages date state using React hooks, and shows a functional date range selection example. It also includes comments on important global CSS settings and common props for the picker.

import React, { useState } from 'react';
import 'react-dates/initialize';
import { DateRangePicker } from 'react-dates';
import 'react-dates/lib/css/_datepicker.css';
import moment from 'moment';

// IMPORTANT: Ensure global box-sizing: border-box for correct layout.
// Add this to your global CSS (e.g., index.css or App.css):
/*
html {
  box-sizing: border-box;
}
*,
*::before,
*::after {
  box-sizing: inherit;
}
*/

function MyDateRangePickerApp() {
  const [startDate, setStartDate] = useState(null);
  const [endDate, setEndDate] = useState(null);
  const [focusedInput, setFocusedInput] = useState(null);

  return (
    <div style={{ padding: '20px' }}>
      <h1>Book Your Stay</h1>
      <p>Select your desired check-in and check-out dates.</p>
      <DateRangePicker
        startDate={startDate} // momentPropTypes.momentObj or null
        startDateId="your_unique_start_date_id"
        endDate={endDate} // momentPropTypes.momentObj or null
        endDateId="your_unique_end_date_id"
        onDatesChange={({ startDate, endDate }) => {
          setStartDate(startDate);
          setEndDate(endDate);
        }}
        focusedInput={focusedInput} // PropTypes.oneOf([START_DATE, END_DATE]) or null
        onFocusChange={input => setFocusedInput(input)}
        orientation="horizontal"
        numberOfMonths={2}
        isOutsideRange={() => false} // Example: Allow all dates
        minimumNights={0}
        displayFormat="MM/DD/YYYY"
        hideKeyboardShortcutsPanel={true}
      />
      {startDate && endDate && (
        <p>
          Selected: {startDate.format('MM/DD/YYYY')} - {endDate.format('MM/DD/YYYY')}
        </p>
      )}
    </div>
  );
}

export default MyDateRangePickerApp;

view raw JSON →