Headless

The headless package (react-date-range-picker-headless) provides unstyled hooks and context providers. It contains all the state management, calendar logic, keyboard navigation, and accessibility features — but zero CSS, zero markup opinions.

You bring your own UI.

Installation

npm install react-date-range-picker-headless

When to Use Headless

You have a design system with its own component library
You want pixel-perfect control over every element
You are building a custom date picker for a specific use case
You want to integrate with a CSS framework not covered by the styled packages

If you want ready-to-use styled components, see Styled, Tailwind v4, or Tailwind v3 instead.

How It Works

Pick a hook based on your use case
Pass options (value, onChange, config)
Get back state and handlers
Render your own UI using the returned values

import { useState } from "react";
import { useDatePicker } from "react-date-range-picker-headless";

function MyDatePicker() {
  const [value, setValue] = useState<Date | null>(null);

  const {
    isOpen,
    calendar,
    getDayProps,
    displayValue,
    handleToggle,
    handleDateClick,
    handleConfirm,
    handlePrevMonth,
    handleNextMonth,
    locale,
  } = useDatePicker({ value, onChange: setValue });

  return (
    <div>
      <button onClick={handleToggle}>{displayValue || locale.placeholder}</button>
      {isOpen && (
        <div>
          <div>
            <button onClick={handlePrevMonth}>{locale.prevMonth}</button>
            <span>{locale.formatMonthYear(calendar.month)}</span>
            <button onClick={handleNextMonth}>{locale.nextMonth}</button>
          </div>
          <div style={{ display: "grid", gridTemplateColumns: "repeat(7, 1fr)" }}>
            {calendar.weeks.flat().map((day, i) => {
              if (!day) return <span key={i} />;
              const props = getDayProps(day);
              return (
                <button
                  key={i}
                  onClick={() => handleDateClick(day)}
                  style={{
                    background: props.isSelected ? "#0ea5e9" : "transparent",
                    color: props.isDisabled ? "#ccc" : props.isToday ? "#0ea5e9" : "inherit",
                  }}
                >
                  {props.day}
                </button>
              );
            })}
          </div>
          <button onClick={handleConfirm}>{locale.confirm}</button>
        </div>
      )}
    </div>
  );
}

Available Hooks

Hook	Use Case
`useDatePicker`	Single date selection
`useDateRangePicker`	Date range selection with dual calendars
`useDateTimePicker`	Date + time selection
`useDateRangeTimePicker`	Date range + time selection
`useTimePicker`	Time-only scroll wheel
`useStandaloneTimePicker`	Time picker with open/close behavior

Next Steps

Building Custom UI — Full walkthrough of the headless pattern
Hooks Reference — Detailed hook documentation
Contexts — Provider pattern for compound components
Date Utilities — Helper functions exported from headless