useDatePicker

El hook principal para la selección de una única fecha. Gestiona el estado del calendario, el comportamiento de abrir/cerrar, la navegación por teclado y el formato de fecha.

Importar

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

Uso

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}>
{/* Encabezado del calendario */}
<button onClick={picker.handlePrevMonth}>{picker.locale.prevMonth}</button>
<span>{picker.locale.formatMonthYear(picker.calendar.month)}</span>
<button onClick={picker.handleNextMonth}>{picker.locale.nextMonth}</button>
{/* Cuadrícula del calendario */}
{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>
);
})}
{/* Pie de página */}
<button onClick={picker.handleConfirm}>{picker.locale.confirm}</button>
</div>
)}
</div>
);
}

Opciones

OpciónTipoPor defectoDescripción
valueDate | nullRequerido. La fecha actualmente seleccionada.
onChange(date: Date | null) => voidRequerido. Se llama cuando la selección de fecha cambia.
minDateDateLa fecha más temprana que se puede seleccionar.
maxDateDateLa fecha más tardía que se puede seleccionar.
localePartial<Locale>DEFAULT_LOCALESobrescribe las cadenas de texto de la localización.
initialMonthDateMes a mostrar inicialmente (por defecto el valor o la fecha de hoy).
sizeDatePickerSizePropiedad de paso para componentes con estilo. Los hooks headless ignoran esto.
weekStartsOnWeekDay"sunday"Primer día de la semana.
isDateUnavailable(date: Date) => booleanFunción personalizada para deshabilitar fechas específicas.
displayFormatstringCadena de formato personalizada para el valor mostrado (ej. "YYYY/MM/DD").
openbooleanEstado de apertura controlado. Cuando se proporciona, el hook no gestiona el estado de apertura internamente.
initialOpenbooleanfalseEstado de apertura inicial (modo no controlado).
onOpenChange(open: boolean) => voidCallback que se ejecuta cuando el estado de apertura cambia. Funciona con los modos controlado y no controlado.
requiredbooleanfalseCuando es true, handleClear no hace nada.
todayDatenew Date()Sobrescribe la fecha de hoy para los cálculos de isToday y disablePast/disableFuture.
onMonthChange(month: Date) => voidCallback que se ejecuta cuando el mes mostrado cambia.
disablePastbooleanfalseDeshabilita todas las fechas anteriores a hoy.
disableFuturebooleanfalseDeshabilita todas las fechas posteriores a hoy.
showOutsideDaysbooleanfalseMuestra los días de los meses adyacentes para rellenar la cuadrícula de 6 semanas.
highlightDatesDate[]Array de fechas a resaltar en el calendario.
shouldCloseOnSelectbooleanfalseConfirma automáticamente y cierra al hacer clic en una fecha.
numberOfMonthsnumber1Número de meses a mostrar simultáneamente.
captionLayoutCaptionLayout"buttons""buttons" para las flechas de anterior/siguiente, "dropdown" para los selectores de año/mes.
fromYearnumbercurrent year - 100Año de inicio para el modo de lista desplegable.
toYearnumbercurrent year + 10Año de fin para el modo de lista desplegable.

Valores de Retorno

NombreTipoDescripción
isOpenbooleanIndica si el popup está abierto.
tempDateDate | nullFecha seleccionada temporalmente (antes de la confirmación).
currentMonthDateEl mes que se muestra actualmente.
localeLocaleObjeto de localización resuelto con todas las cadenas.
calendarCalendarMonthDatos del calendario para el mes actual (incluye month, days, weeks).
calendarsCalendarMonth[]Array de meses del calendario (longitud = numberOfMonths).
getDayProps(date: Date, referenceMonth?: Date) => DayPropsCalcula los indicadores para la celda de un día del calendario.
displayValuestringCadena formateada del valor confirmado.
hasValuebooleanIndica si una fecha está confirmada actualmente.
canConfirmbooleanIndica si la selección actual es válida para ser confirmada.
handleDateClick(date: Date) => voidManeja el clic en la celda de un día.
handlePrevMonth() => voidNavega al mes anterior.
handleNextMonth() => voidNavega al mes siguiente.
handleOpen() => voidAbre el popup.
handleClose() => voidCierra el popup (descarta los cambios no guardados).
handleToggle() => voidAlterna la visibilidad del popup.
handleConfirm() => voidConfirma la selección y cierra.
handleCancel() => voidCancela y revierte al valor anterior.
handleClear() => voidLimpia el valor (no hace nada si es required).
handleGoToToday() => voidNavega el calendario al mes de hoy.
containerRefRefObject<HTMLDivElement | null>Asociar al elemento contenedor para la detección de clics externos.
popupRefRefObject<HTMLDivElement | null>Asociar al elemento del popup.
focusedDateDate | nullFecha actualmente enfocada por el teclado.
handleKeyDown(e: KeyboardEvent<HTMLElement>) => voidManejador de eventos de teclado para las flechas, Enter, Escape, Tab.
yearsnumber[]Array de años para el modo de encabezado con lista desplegable.
monthsnumber[]Array de índices de mes (0-11) para el modo de encabezado con lista desplegable.
handleYearSelect(year: number, calendarIndex?: number) => voidEstablece el año mostrado (modo de lista desplegable).
handleMonthSelect(month: number, calendarIndex?: number) => voidEstablece el mes mostrado (modo de lista desplegable).

Comportamientos Clave

Estado de Apertura Controlado vs No Controlado

Por defecto, el hook gestiona el estado de abrir/cerrar internamente. Para controlarlo externamente, pasa open y onOpenChange:

const [isOpen, setIsOpen] = useState(false);
const picker = useDatePicker({
value: date,
onChange: setDate,
open: isOpen,
onOpenChange: setIsOpen,
});

shouldCloseOnSelect

Cuando shouldCloseOnSelect es true, hacer clic en una fecha confirma y cierra inmediatamente el popup, omitiendo el paso de confirmación explícita.

TeclaAcción
Flechas Arriba/Abajo/Izquierda/DerechaMover el foco entre los días
Enter / EspacioSeleccionar la fecha enfocada
EscapeCancelar y cerrar
TabMover el foco dentro del popup

Encabezado con Lista Desplegable

Cuando captionLayout es "dropdown", el encabezado muestra listas desplegables para seleccionar el año y el mes en lugar de los botones de anterior/siguiente. Usa years, months, handleYearSelect y handleMonthSelect para renderizar las listas desplegables.