useDatePicker

The core hook for single date selection. It manages calendar state, open/close behavior, keyboard navigation, and date formatting.

Import

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

Usage

import { useState } from "react";
import { useDatePicker } from "react-date-range-picker-headless";
function MyDatePicker() {
const [date, setDate] = useState<Date | null>(null);
const picker = useDatePicker({
value: date,
onChange: setDate,
});
return (
<div ref={picker.containerRef}>
<button onClick={picker.handleToggle}>
{picker.displayValue || picker.locale.placeholder}
</button>
{picker.isOpen && (
<div ref={picker.popupRef} onKeyDown={picker.handleKeyDown}>
{/* Calendar header */}
<button onClick={picker.handlePrevMonth}>{picker.locale.prevMonth}</button>
<span>{picker.locale.formatMonthYear(picker.calendar.month)}</span>
<button onClick={picker.handleNextMonth}>{picker.locale.nextMonth}</button>
{/* Calendar grid */}
{picker.calendar.weeks.flat().map((day, i) => {
if (!day) return <span key={i} />;
const dp = picker.getDayProps(day);
return (
<button key={i} onClick={() => picker.handleDateClick(day)} disabled={dp.isDisabled}>
{dp.day}
</button>
);
})}
{/* Footer */}
<button onClick={picker.handleConfirm}>{picker.locale.confirm}</button>
</div>
)}
</div>
);
}

Options

OptionTypeDefaultDescription
valueDate | nullThe selected date. (controlled)
onChange(date: Date | null) => voidCallback function invoked when a date is selected.
minDateDateThe minimum selectable date.
maxDateDateThe maximum selectable date.
localePartial<Locale>enLocale object for internationalization.
initialMonthDatenew Date()The month to display initially. If value is provided, it will be the month of that date.
size"x-large" | "large" | "medium" | "small""medium"The size of the picker. Affects the styled version.
weekStartsOn"sunday" - "saturday""sunday"The day the week starts on.
isDateUnavailable(date: Date) => booleanFunction to disable a specific date. Returning true disables it.
displayFormatstringDepends on localeThe format of the date string displayed in the input.
openbooleanControls the open/closed state of the picker. (controlled component)
initialOpenbooleanfalseSets the initial open/closed state of the picker. (uncontrolled component)
onOpenChange(open: boolean) => voidCallback when the open state changes.
requiredbooleanfalseIf true, the value cannot be cleared.
todayDatenew Date()Overrides the concept of “today”.
onMonthChange(month: Date) => voidCallback when the displayed month changes.
disablePastbooleanfalseIf true, all dates before today are disabled.
disableFuturebooleanfalseIf true, all dates after today are disabled.
showOutsideDaysbooleanfalseIf true, shows dates from the previous and next month in the calendar.
highlightDatesDate[][]Array of dates to highlight.
shouldCloseOnSelectbooleantrueIf true, the picker will close after selecting a date.
inlinebooleanfalseIf true, the calendar is always visible instead of in a popup.
numberOfMonthsnumber1Number of months to display.
captionLayout"buttons" | "dropdown""buttons"The layout for month/year navigation.
fromYearnumbertoday - 100 yearsThe start year for the year dropdown.
toYearnumbertoday + 10 yearsThe end year for the year dropdown.