useStandaloneTimePicker

Gestiona el estado del tiempo con comportamiento de abrir/cerrar y clic fuera.

Import

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

Uso

import { useState } from "react";
import { useStandaloneTimePicker } from "react-date-range-picker-headless";
function MyTimePicker() {
const [time, setTime] = useState<Date | null>(null);
const picker = useStandaloneTimePicker({
value: time,
onChange: setTime,
time: { precision: "minute", hourFormat: "24", minuteStep: 5 },
placeholder: "Seleccionar hora",
});
return (
<div ref={picker.containerRef}>
<button onClick={picker.handleToggle}>
{picker.hasValue ? picker.displayValue : "Seleccionar hora"}
</button>
{picker.isOpen && (
<div ref={picker.popupRef} onKeyDown={picker.handleKeyDown}>
<div>
<span>{String(picker.tempHour).padStart(2, "0")}</span>
<span>:</span>
<span>{String(picker.tempMinute).padStart(2, "0")}</span>
</div>
{/* Conectar controles de hora/minuto */}
<input
type="range"
min={0}
max={23}
value={picker.tempHour}
onChange={(e) => picker.handleHourChange(Number(e.target.value))}
/>
<input
type="range"
min={0}
max={55}
step={5}
value={picker.tempMinute}
onChange={(e) => picker.handleMinuteChange(Number(e.target.value))}
/>
<div>
<button onClick={picker.handleClear}>Limpiar</button>
<button onClick={picker.handleCancel}>Cancelar</button>
<button onClick={picker.handleConfirm}>Confirmar</button>
</div>
</div>
)}
</div>
);
}

Opciones

OpciónTipoPor defectoDescripción
valueDate | nullRequerido. Hora actual como un objeto Date (solo se usa la porción de la hora).
onChange(date: Date | null) => voidRequerido. Se llama cuando se confirma la hora.
timeTimeConfig{ precision: "minute", hourFormat: "24", minuteStep: 5, secondStep: 1 }Configuración del selector de hora.
localePartial<Locale>DEFAULT_LOCALESobrescribir las cadenas de la localización.
displayFormatstringCadena de formato personalizada para la visualización del disparador.
placeholderstringTexto de marcador de posición cuando no se ha seleccionado ningún valor.
openbooleanEstado de apertura controlado.
initialOpenbooleanfalseEstado de apertura inicial (no controlado).
onOpenChange(open: boolean) => voidCallback cuando cambia el estado de apertura.
requiredbooleanfalseCuando es verdadero, handleClear no hace nada.
inlinebooleanfalseMostrar siempre el panel sin un disparador/popup.
namestringNombre del input oculto para el envío del formulario.

Valores de Retorno

NombreTipoDescripción
isOpenbooleanIndica si el popup está actualmente abierto.
handleOpen() => voidAbre el popup.
handleClose() => voidCierra el popup.
handleToggle() => voidAlterna el popup.
tempHournumberValor de hora temporal actual.
tempMinutenumberValor de minuto temporal actual.
tempSecondnumberValor de segundo temporal actual.
tempPeriodTimePeriodPeríodo AM/PM actual.
handleHourChange(hour: number) => voidActualiza la hora temporal.
handleMinuteChange(minute: number) => voidActualiza el minuto temporal.
handleSecondChange(second: number) => voidActualiza el segundo temporal.
handlePeriodChange(period: TimePeriod) => voidActualiza el período AM/PM.
handleConfirm() => voidConfirma la hora temporal, llama a onChange y cierra el popup.
handleCancel() => voidRevierte al valor original y cierra el popup.
handleClear() => voidLimpia el valor y cierra. No hace nada si es required.
displayValuestringCadena de hora formateada para el disparador (valor confirmado).
timeDisplayValuestringCadena de hora formateada para el panel (valor temporal).
hasValuebooleanIndica si se ha establecido un valor de hora.
canConfirmbooleanIndica si el botón de confirmar debe estar habilitado.
localeLocaleObjeto de localización resuelto.
resolvedTimeConfigRequired<TimeConfig>Configuración de hora completamente resuelta.
containerRefRefObject<HTMLDivElement | null>Ref para el contenedor exterior (usado para la detección de clic fuera).
popupRefRefObject<HTMLDivElement | null>Ref para el elemento del popup (usado para la detección de clic fuera).
handleKeyDown(e: KeyboardEvent) => voidManejador de teclado (Escape para cancelar).

Comportamientos Clave

Abrir/Cerrar

El popup puede ser controlado o no controlado. Cuando se proporciona open, el hook lo usa como la fuente de verdad. De lo contrario, se utiliza el estado interno con initialOpen como valor inicial.

Clic Afuera

Hacer clic fuera de containerRef y popupRef activa handleCancel, revirtiendo al valor original y cerrando el popup.

Teclado

Presionar Escape mientras el popup está abierto activa handleCancel.

Modo en Línea

Cuando inline es true, el panel siempre está visible y los cambios se aplican inmediatamente (sincronización automática). La lógica de abrir/cerrar se omite.

Patrón de Estado Temporal

Este hook mantiene un estado temporal que solo se confirma cuando se llama a handleConfirm:

  • handleConfirm — escribe el estado temporal en onChange y cierra el popup
  • handleCancel — revierte el estado temporal al value actual y cierra
  • handleClear — llama a onChange(null) y cierra

Valores de Visualización

  • displayValue — cadena formateada del value confirmado (para el disparador)
  • timeDisplayValue — cadena formateada de los valores temporales (para el panel)