Date Time Range Flow Picker

A flexible and customizable date-time range picker component built with React, TypeScript, and Material-UI. This component provides an intuitive flow-based interface for selecting date ranges with optional time selection.

Features

• 🗓️ Date Range Selection - Select start and end dates with visual range highlighting
• ⏰ Time Selection - Optional time picker with 12/24 hour format support
• 📱 Responsive Design - Works seamlessly on desktop and mobile devices
• 🎨 Material-UI Integration - Built with Material-UI components for consistent styling
• 🔄 Dialog & Popover Modes - Choose between dialog or popover display modes
• ⚡ Customizable - Extensive props for customization
• 📦 TypeScript Support - Full TypeScript definitions included
• 🎯 Accessible - Built with accessibility in mind

Installation

npm install date-time-range-flow-picker

or

yarn add date-time-range-flow-picker

Peer Dependencies

This package requires the following peer dependencies:

• react (>=16.8.0)
• react-dom (>=16.8.0)
• @mui/material (>=5.0.0)
• @mui/icons-material (>=5.0.0)
• dayjs (>=1.11.0)

Make sure these are installed in your project:

npm install react react-dom @mui/material @mui/icons-material dayjs

Basic Usage

Styles are automatically injected when you import the component — no separate CSS import needed.

import React, { useState, useRef } from 'react';
import DateTimeRangeFlowPicker, { DateTimeRangeFlowPickerHandle } from 'date-time-range-flow-picker';

function App() {
  const [dateRange, setDateRange] = useState({
    startDate: null as Date | null,
    endDate: null as Date | null,
  });

  const pickerRef = useRef<DateTimeRangeFlowPickerHandle>(null);

  return (
    <div>
      <button onClick={() => pickerRef.current?.openStart()}>
        Select Date Range
      </button>

      <DateTimeRangeFlowPicker
        ref={pickerRef}
        value={dateRange}
        onChange={setDateRange}
        calendarTimeFormat={12}
        totalMonthlyDays={28}
      />
    </div>
  );
}

Props

Required Props

| Prop | Type | Description | |------|------|-------------| | value | DateValueType | Current date range value with startDate and endDate | | onChange | (value: DateValueType) => void | Callback when date range changes |

Optional Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onClose | () => void | - | Callback when picker closes | | monthsToShow | number | 12 | Number of months to show (only works when isPreviousDatesDisabled = true) | | minDate | Date | - | Minimum selectable date | | useRange | boolean | true | Enable date range selection | | showFooter | boolean | true | Show footer with day/week/month shortcuts | | jumpToTimeAfterSelectingDate | boolean | false | Automatically jump to time picker after selecting date | | startDateText | string | "Start Reservation" | Label for start date | | endDateText | string | "End Reservation" | Label for end date | | isStartDateDisabled | boolean | false | Disable start date selection | | isEndDateDisabled | boolean | false | Disable end date selection | | isPreviousDatesDisabled | boolean | false | Disable dates before today | | isOnlyStartDate | boolean | false | Use only start date (single date mode) | | isOnlyEndDate | boolean | false | Use only end date (single date mode) | | showTime | boolean | true | Show time picker | | mode | "dialog" \| "popover" | "dialog" | Display mode | | position | "top" \| "bottom" \| "left" \| "right" | "bottom" | Popover position (only for popover mode) | | anchorEl | HTMLElement \| null | null | Anchor element for popover | | showArrowsToLoadYear | boolean | false | Show arrows to navigate years | | calendarTimeFormat | 12 \| 24 | 12 | Time format (12 or 24 hour) | | totalMonthlyDays | number | 28 | Total days in a month for calculations |

Examples

Basic Date Range Picker

import React, { useState, useRef } from 'react';
import DateTimeRangeFlowPicker, { DateTimeRangeFlowPickerHandle } from 'date-time-range-flow-picker';

function DateRangeExample() {
  const [dateRange, setDateRange] = useState({
    startDate: null as Date | null,
    endDate: null as Date | null,
  });

  const pickerRef = useRef<DateTimeRangeFlowPickerHandle>(null);

  return (
    <div>
      <button onClick={() => pickerRef.current?.openStart()}>
        Open Date Picker
      </button>

      <DateTimeRangeFlowPicker
        ref={pickerRef}
        value={dateRange}
        onChange={setDateRange}
      />
    </div>
  );
}

Popover Mode

import React, { useState, useRef, useState as useStateHook } from 'react';
import DateTimeRangeFlowPicker, { DateTimeRangeFlowPickerHandle } from 'date-time-range-flow-picker';

function PopoverExample() {
  const [dateRange, setDateRange] = useState({
    startDate: null as Date | null,
    endDate: null as Date | null,
  });

  const [anchorEl, setAnchorEl] = useStateHook<HTMLElement | null>(null);
  const pickerRef = useRef<DateTimeRangeFlowPickerHandle>(null);

  return (
    <div>
      <button 
        onClick={(e) => {
          setAnchorEl(e.currentTarget);
          pickerRef.current?.openStart();
        }}
      >
        Open Popover
      </button>

      <DateTimeRangeFlowPicker
        ref={pickerRef}
        value={dateRange}
        onChange={setDateRange}
        mode="popover"
        anchorEl={anchorEl}
        position="bottom"
      />
    </div>
  );
}

Single Date Selection

import React, { useState, useRef } from 'react';
import DateTimeRangeFlowPicker, { DateTimeRangeFlowPickerHandle } from 'date-time-range-flow-picker';

function SingleDateExample() {
  const [dateRange, setDateRange] = useState({
    startDate: null as Date | null,
    endDate: null as Date | null,
  });

  const pickerRef = useRef<DateTimeRangeFlowPickerHandle>(null);

  return (
    <DateTimeRangeFlowPicker
      ref={pickerRef}
      value={dateRange}
      onChange={setDateRange}
      useRange={false}
      isOnlyStartDate={true}
      startDateText="Select Date"
    />
  );
}

24-Hour Format with Custom Settings

import React, { useState, useRef } from 'react';
import DateTimeRangeFlowPicker, { DateTimeRangeFlowPickerHandle } from 'date-time-range-flow-picker';

function CustomFormatExample() {
  const [dateRange, setDateRange] = useState({
    startDate: null as Date | null,
    endDate: null as Date | null,
  });

  const pickerRef = useRef<DateTimeRangeFlowPickerHandle>(null);

  return (
    <DateTimeRangeFlowPicker
      ref={pickerRef}
      value={dateRange}
      onChange={setDateRange}
      calendarTimeFormat={24}
      totalMonthlyDays={30}
      isPreviousDatesDisabled={true}
      jumpToTimeAfterSelectingDate={true}
    />
  );
}

Ref Methods

The component exposes methods through a ref:

const pickerRef = useRef<DateTimeRangeFlowPickerHandle>(null);

// Open picker at start date step
pickerRef.current?.openStart();

// Open picker at end date step
pickerRef.current?.openEnd();

TypeScript

Full TypeScript support is included. Import types as needed:

import type {
  DateValueType,
  DateTimeRangeFlowPickerHandle,
  ActiveStep,
  Props,
} from 'date-time-range-flow-picker';

Styling

The component uses Tailwind CSS classes for styling. Make sure your project has Tailwind CSS configured, or the component will need to be styled accordingly.

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

For issues, questions, or contributions, please visit the GitHub repository.