react-dates

react-dates is a set of fully controlled React components for picking a single date or a date range, originally built by Airbnb for booking-style search forms. It ships DateRangePicker and SingleDatePicker as ready-to-use, keyboard-accessible inputs with a calendar popover, plus lower-level DayPickerRangeController and DayPickerSingleDateController components for teams that want to build their own picker UI on top of the same date logic.

Under the hood it relies on moment.js for date arithmetic and formatting, and exposes hooks such as minDate/maxDate, isDayBlocked, and isOutsideRange for enforcing custom availability rules. Text is routed through a phrases object so every label can be localized, and visual styling is pluggable via react-with-styles, so consumers can theme the calendar with Aphrodite, CSS, or another styling interface without forking component code.

What You Get

• Controlled DateRangePicker and SingleDatePicker components with input fields, calendar popovers, and full keyboard/screen-reader support
• Headless DayPickerRangeController and DayPickerSingleDateController components for building a completely custom picker UI on the same date logic
• Moment.js-backed date constraints (minDate, maxDate, isDayBlocked, isOutsideRange, isDayHighlighted) for enforcing custom availability and booking rules
• A phrases-based internationalization system plus locale-aware displayFormat/monthFormat options for translated calendars
• Pluggable theming through react-with-styles, letting consumers style the calendar with Aphrodite, plain CSS, or another styling interface

Common Use Cases

• Travel and booking search forms where DateRangePicker lets users pick check-in/check-out or departure/return dates
• Admin dashboards and analytics tools that filter reports by a custom date range
• Reservation and scheduling forms that need a single accessible date input via SingleDatePicker
• Products that need a fully custom calendar UI, built on the headless DayPickerRangeController/DayPickerSingleDateController controllers

Under The Hood

Architecture The library layers three tiers: presentational day/week/month primitives (CalendarDay.jsx, CalendarMonth.jsx, CalendarMonthGrid.jsx, CalendarWeek.jsx), headless range/single controllers that own selection and navigation state (DayPickerRangeController.jsx, DayPickerSingleDateController.jsx — each well over a thousand lines encapsulating focus, visible-month, and modifier logic), and top-level input components (DateRangePicker.jsx, SingleDatePicker.jsx, DateRangePickerInputController.jsx) that wrap a controller with text inputs, a portal-aware popover, and outside-click handling via react-outside-click-handler. Shape validation for every public prop set lives in src/shapes (DateRangePickerShape.js, SingleDatePickerShape.js, ModifiersShape.js, etc.), making the controller/input split explicit and swappable — a consumer can drop the input layer entirely and drive a controller directly.

Tech Stack A React component library (peer dependency on React 0.14–16.x) using moment.js for all date math and formatting, react-with-styles plus react-with-styles-interface-css for theming, react-portal and consolidated-events for popover positioning and outside-click detection, and airbnb-prop-types/prop-types for runtime prop validation. It builds through Babel with env-specific presets (babel-preset-airbnb) into separate CJS and ESM outputs, and CSS is generated by a dedicated build:css script rather than authored as CSS-in-JS output directly.

Code Quality Tests live under test/components and test/utils and run through Mocha with Enzyme for shallow/mount rendering and Sinon for spies, executed both via a standard Node test script and via Karma for real-browser runs — a dual setup that catches DOM-specific behavior standard Node-based tests would miss. ESLint runs on every pretest with eslint-config-airbnb, and nyc reports coverage. Prop types are declared explicitly per component via the shapes/ directory instead of using TypeScript, which is workable but weaker than compile-time enforcement, and the project has no bundled type declarations.

What Makes It Unique Most date-picker libraries expose only a finished input widget; react-dates additionally exposes its DayPickerRangeController/DayPickerSingleDateController as public, documented components so teams can keep all of the date-selection, keyboard-navigation, and constraint logic while replacing the input/popover chrome entirely — a middle ground between a black-box widget and building a calendar from scratch.