tessl/npm-react-dates

A responsive and accessible date range picker component built with React

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

React Dates

Name: tessl/npm-react-dates
Author: tessl

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

Install with Tessl CLI