or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

calendar-components.mdcalendar-controllers.mdindex.mdinput-components.mdmain-pickers.mdutilities.md
tile.json

tessl/npm-react-dates

A responsive and accessible date range picker component built with React

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/react-dates@21.8.x

To install, run

npx @tessl/cli install tessl/npm-react-dates@21.8.0

index.mddocs/

React Dates

React Dates is a comprehensive, responsive, and accessible date picker library built with React. It provides three main date selection components with extensive customization options, accessibility features, and internationalization support through Moment.js integration.

Package Information

  • Package Name: react-dates
  • Package Type: npm
  • Language: JavaScript/React
  • Installation: npm install react-dates

Core Imports

import {
  DateRangePicker,
  SingleDatePicker,
  DayPickerRangeController
} from "react-dates";

For CommonJS:

const {
  DateRangePicker,
  SingleDatePicker,
  DayPickerRangeController
} = require("react-dates");

Basic Usage

import React, { useState } from "react";
import {
  DateRangePicker,
  SingleDatePicker
} from "react-dates";
import moment from "moment";

// Required: Initialize CSS interface
import "react-dates/initialize";
// Required: Import CSS styles
import "react-dates/lib/css/_datepicker.css";

// Date Range Picker
function MyDateRangePicker() {
  const [startDate, setStartDate] = useState(null);
  const [endDate, setEndDate] = useState(null);
  const [focusedInput, setFocusedInput] = useState(null);

  return (
    <DateRangePicker
      startDate={startDate}
      startDateId="your_unique_start_date_id"
      endDate={endDate}
      endDateId="your_unique_end_date_id"
      onDatesChange={({ startDate, endDate }) => {
        setStartDate(startDate);
        setEndDate(endDate);
      }}
      focusedInput={focusedInput}
      onFocusChange={setFocusedInput}
    />
  );
}

// Single Date Picker
function MySingleDatePicker() {
  const [date, setDate] = useState(null);
  const [focused, setFocused] = useState(false);

  return (
    <SingleDatePicker
      date={date}
      onDateChange={setDate}
      focused={focused}
      onFocusChange={({ focused }) => setFocused(focused)}
      id="your_unique_id"
    />
  );
}

Architecture

React Dates is built around several key components:

  • Main Pickers: High-level date picker components with input fields and calendar displays
  • Controller Components: Headless calendar components for custom implementations
  • Input Components: Standalone input field components for custom layouts
  • Calendar Components: Low-level calendar rendering components
  • Utility Functions: Date comparison and conversion helpers
  • Shape Definitions: PropTypes validation schemas

The library emphasizes accessibility with screen reader support, keyboard navigation, and ARIA labeling. It supports responsive design with multiple orientations, portal rendering, and mobile-optimized layouts.

Capabilities

Main Date Pickers

Complete date picker components with input fields and calendar dropdowns. Perfect for forms and user interfaces requiring date selection.

// Date range selection component
function DateRangePicker(props: DateRangePickerProps): ReactElement;

// Single date selection component  
function SingleDatePicker(props: SingleDatePickerProps): ReactElement;

Main Date Pickers

Calendar Controllers

Headless calendar components without input fields, ideal for custom implementations and embedded calendars.

// Calendar-only date range controller
function DayPickerRangeController(props: DayPickerRangeControllerProps): ReactElement;

// Calendar-only single date controller
function DayPickerSingleDateController(props: DayPickerSingleDateControllerProps): ReactElement;

Calendar Controllers

Input Components

Standalone input field components for custom layouts and advanced use cases.

// Date range input fields
function DateRangePickerInput(props: DateRangePickerInputProps): ReactElement;
function DateRangePickerInputController(props: DateRangePickerInputControllerProps): ReactElement;

// Single date input field
function SingleDatePickerInput(props: SingleDatePickerInputProps): ReactElement;

Input Components

Calendar Components

Low-level calendar rendering components for building custom date picker interfaces.

// Complete calendar component with navigation
function DayPicker(props: DayPickerProps): ReactElement;

// Month grid layout for multiple months
function CalendarMonthGrid(props: CalendarMonthGridProps): ReactElement;

// Individual month view
function CalendarMonth(props: CalendarMonthProps): ReactElement;

// Individual day cell
function CalendarDay(props: CalendarDayProps): ReactElement;

Calendar Components

Utility Functions

Date comparison and conversion utilities for working with Moment.js objects.

// Date comparison functions
function isSameDay(a: moment.Moment, b: moment.Moment): boolean;
function isInclusivelyAfterDay(a: moment.Moment, b: moment.Moment): boolean;
function isInclusivelyBeforeDay(a: moment.Moment, b: moment.Moment): boolean;
function isNextDay(a: moment.Moment, b: moment.Moment): boolean;

// Date conversion functions
function toISODateString(date: moment.Moment | string, currentFormat?: string): string;
function toLocalizedDateString(date: moment.Moment | string, currentFormat?: string): string;
function toMomentObject(dateString: string, customFormat?: string): moment.Moment | null;

Utility Functions

Common Constants

React Dates exports several constants for configuration:

// Import constants from react-dates
import {
  START_DATE,
  END_DATE,
  HORIZONTAL_ORIENTATION,
  VERTICAL_ORIENTATION,
  VERTICAL_SCROLLABLE,
  ICON_BEFORE_POSITION,
  ICON_AFTER_POSITION,
  ANCHOR_LEFT,
  ANCHOR_RIGHT,
  OPEN_DOWN,
  OPEN_UP,
  NAV_POSITION_TOP,
  NAV_POSITION_BOTTOM,
  INFO_POSITION_TOP,
  INFO_POSITION_BOTTOM,
  INFO_POSITION_BEFORE,
  INFO_POSITION_AFTER,
  DISPLAY_FORMAT,
  ISO_FORMAT,
  DAY_SIZE,
  WEEKDAYS
} from "react-dates";

// Focus states for date range picker
START_DATE: "startDate";
END_DATE: "endDate";

// Orientation options
HORIZONTAL_ORIENTATION: "horizontal";
VERTICAL_ORIENTATION: "vertical";
VERTICAL_SCROLLABLE: "verticalScrollable";

// Icon positions
ICON_BEFORE_POSITION: "before";
ICON_AFTER_POSITION: "after";

// Anchor directions
ANCHOR_LEFT: "left";
ANCHOR_RIGHT: "right";

// Open directions
OPEN_DOWN: "down";
OPEN_UP: "up";

// Navigation positions
NAV_POSITION_TOP: "navPositionTop";
NAV_POSITION_BOTTOM: "navPositionBottom";

// Info panel positions
INFO_POSITION_TOP: "top";
INFO_POSITION_BOTTOM: "bottom";
INFO_POSITION_BEFORE: "before";
INFO_POSITION_AFTER: "after";

// Date formats
DISPLAY_FORMAT: "L";
ISO_FORMAT: "YYYY-MM-DD";

// Layout constants
DAY_SIZE: 39;
WEEKDAYS: [0, 1, 2, 3, 4, 5, 6];

// Validation function types
type DayValidationFunction = (day: moment.Moment) => boolean;

// Date change handlers
type DateRangeChangeHandler = ({ startDate, endDate }: {
  startDate: moment.Moment | null;
  endDate: moment.Moment | null;
}) => void;

type SingleDateChangeHandler = (date: moment.Moment | null) => void;

// Focus change handlers
type FocusChangeHandler = (focusedInput: 'startDate' | 'endDate' | null) => void;
type SingleFocusChangeHandler = ({ focused }: { focused: boolean }) => void;

Accessibility Features

  • Screen Reader Support: Complete ARIA labeling and screen reader announcements
  • Keyboard Navigation: Arrow keys, Tab, Enter, Escape key support
  • Focus Management: Proper focus indicators and logical tab order
  • Customizable Labels: Override all text for localization and accessibility needs

Required Initialization

React Dates requires CSS interface initialization before use:

// Import and run initialization (required)
import "react-dates/initialize";

// Or manually initialize
import { registerCSSInterfaceWithDefaultTheme } from "react-dates/lib/initialize";
registerCSSInterfaceWithDefaultTheme();

CSS Import

You must also import the required CSS styles:

@import '~react-dates/lib/css/_datepicker.css';

Or include it in your HTML:

<link rel="stylesheet" type="text/css" href="./node_modules/react-dates/lib/css/_datepicker.css" />

Common Validation Patterns

// Block past dates
const isOutsideRange = (day) => moment().diff(day) > 0;

// Block specific dates
const isDayBlocked = (day) => {
  const blockedDates = ['2023-12-25', '2023-01-01'];
  return blockedDates.includes(day.format('YYYY-MM-DD'));
};

// Highlight special dates
const isDayHighlighted = (day) => {
  const holidays = ['2023-12-25', '2023-07-04'];
  return holidays.includes(day.format('YYYY-MM-DD'));
};

Error Handling

The library handles validation through callback functions rather than throwing exceptions. Invalid states are communicated through:

  • Blocked dates (non-selectable)
  • Outside range dates (visually distinguished)
  • Custom validation feedback through isDayBlocked and isOutsideRange functions