useDateTimePicker

Hook para seleção combinada de data e hora. Estende useDatePicker com estado de tempo (hora, minuto, segundo, período) e um seletor de tempo aninhado.

Importação

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

Uso

import { useState } from "react";
import { useDateTimePicker } from "react-date-range-picker-headless";
function MyDateTimePicker() {
const [dateTime, setDateTime] = useState<Date | null>(null);
const picker = useDateTimePicker({
value: dateTime,
onChange: setDateTime,
time: { precision: "minute", hourFormat: "24", minuteStep: 5 },
});
return (
<div ref={picker.containerRef}>
<button onClick={picker.handleToggle}>
{picker.displayValue || picker.locale.dateTimePlaceholder}
</button>
{picker.isOpen && (
<div ref={picker.popupRef} onKeyDown={picker.handleKeyDown}>
{/* Calendário (igual ao useDatePicker) */}
<div>
<button onClick={picker.handlePrevMonth}>{picker.locale.prevMonth}</button>
<span>{picker.locale.formatMonthYear(picker.calendar.month)}</span>
<button onClick={picker.handleNextMonth}>{picker.locale.nextMonth}</button>
</div>
{/* ...grade do calendário... */}
{/* Exibição da hora */}
<div>
<span>Hora: {picker.timeDisplayValue}</span>
</div>
{/* Controles de hora */}
<div>
<input
type="number"
value={picker.tempHour}
onChange={(e) => picker.handleHourChange(Number(e.target.value))}
/>
<span>:</span>
<input
type="number"
value={picker.tempMinute}
onChange={(e) => picker.handleMinuteChange(Number(e.target.value))}
/>
</div>
<button onClick={picker.handleConfirm}>{picker.locale.confirm}</button>
</div>
)}
</div>
);
}

Opções

OpçãoTipoPadrãoDescrição
valueDate | nullObrigatório. Valor atual de data e hora.
onChange(dateTime: Date | null) => voidObrigatório. Chamado quando a data e hora mudam.
timeTimeConfig{ precision: "minute", hourFormat: "24", minuteStep: 5, secondStep: 1 }Configuração do seletor de tempo.
minDateDateData selecionável mais antiga.
maxDateDateData selecionável mais recente.
localePartial<Locale>DEFAULT_LOCALESobrescreve as strings de localidade.
initialMonthDateMês inicial a ser exibido.
sizeDatePickerSizePassagem para a UI.
weekStartsOnWeekDay"sunday"Primeiro dia da semana.
isDateUnavailable(date: Date) => booleanFunção personalizada para desabilitar datas específicas.
displayFormatstringString de formato personalizado para o valor de exibição.
openbooleanEstado de abertura controlado.
initialOpenbooleanfalseEstado de abertura inicial.
onOpenChange(open: boolean) => voidCallback para quando o estado de abertura muda.
requiredbooleanfalseQuando verdadeiro, handleClear não faz nada.
todayDatenew Date()Sobrescreve a data de hoje.
onMonthChange(month: Date) => voidCallback para quando o mês muda.
disablePastbooleanfalseDesabilita datas passadas.
disableFuturebooleanfalseDesabilita datas futuras.
showOutsideDaysbooleanfalseMostra os dias do mês adjacente.
highlightDatesDate[]Datas para destacar.
shouldCloseOnSelectbooleanfalsePara seletores de data e hora, aplica-se apenas a cliques em predefinições, não em cliques de data.
numberOfMonthsnumber1Número de meses do calendário.
captionLayoutCaptionLayout"buttons"Modo de layout do cabeçalho.
fromYearnumberano atual - 100Ano inicial para o seletor suspenso.
toYearnumberano atual + 10Ano final para o seletor suspenso.

Valores de Retorno

Estado da Data

NomeTipoDescrição
isOpenbooleanSe o popup está aberto.
tempDateDate | nullData selecionada temporariamente.
currentMonthDateMês atualmente exibido.
localeLocaleObjeto de localidade resolvido.

Estado do Tempo

NomeTipoDescrição
isTimePickerOpenbooleanSe o sub-painel do seletor de tempo está aberto.
tempHournumberValor da hora temporária atual.
tempMinutenumberValor do minuto temporário atual.
tempSecondnumberValor do segundo temporário atual.
tempPeriodTimePeriodPeríodo AM/PM atual ("AM" ou "PM").

Ações de Data

NomeTipoDescrição
handleDateClick(date: Date) => voidLida com o clique na célula do dia.
handlePrevMonth() => voidNavega para o mês anterior.
handleNextMonth() => voidNavega para o próximo mês.
handleOpen() => voidAbre o popup.
handleClose() => voidFecha o popup.
handleToggle() => voidAlterna o popup.
handleConfirm() => voidConfirma data + hora e fecha.
handleCancel() => voidCancela e reverte.
handleClear() => voidLimpa o valor.
handleGoToToday() => voidNavega para hoje.

Ações de Tempo

NomeTipoDescrição
handleHourChange(hour: number) => voidAtualiza a hora.
handleMinuteChange(minute: number) => voidAtualiza o minuto.
handleSecondChange(second: number) => voidAtualiza o segundo.
handlePeriodChange(period: TimePeriod) => voidAlterna AM/PM.
handleTimePickerOpen() => voidAbre o sub-painel do seletor de tempo.
handleTimePickerClose() => voidFecha o sub-painel do seletor de tempo.
handleTimePickerConfirm() => voidConfirma o sub-painel do seletor de tempo.
handleTimePickerCancel() => voidCancela o sub-painel do seletor de tempo.

Computado

NomeTipoDescrição
calendarCalendarMonthDados do calendário para o mês atual.
calendarsCalendarMonth[]Array de meses do calendário.
getDayProps(date: Date, referenceMonth?: Date) => DayPropsProps da célula do dia.
displayValuestringString de data e hora formatada.
timeDisplayValuestringString de hora formatada.
hasValuebooleanSe um valor está confirmado.
canConfirmbooleanSe a confirmação é válida.
containerRefRefObject<HTMLDivElement | null>Ref do contêiner.
popupRefRefObject<HTMLDivElement | null>Ref do popup.
timePickerRefRefObject<HTMLDivElement | null>Ref do sub-painel do seletor de tempo.
focusedDateDate | nullData focada pelo teclado.
handleKeyDown(e: KeyboardEvent<HTMLElement>) => voidManipulador de teclado.
resolvedTimeConfigRequired<TimeConfig>Configuração de tempo resolvida com os padrões preenchidos.
yearsnumber[]Anos para o modo de seletor suspenso.
monthsnumber[]Meses para o modo de seletor suspenso.
handleYearSelect(year: number, calendarIndex?: number) => voidDefine o ano.
handleMonthSelect(month: number, calendarIndex?: number) => voidDefine o mês.

Comportamentos Principais

Configuração de Tempo

A opção time aceita um objeto TimeConfig:

interface TimeConfig {
precision?: "hour" | "minute" | "second"; // default: "minute"
hourFormat?: "12" | "24"; // default: "24"
minuteStep?: 1 | 2 | 3 | 5 | 10 | 15 | 20 | 30; // default: 5
secondStep?: 1 | 2 | 3 | 5 | 10 | 15 | 20 | 30; // default: 1
itemHeight?: number; // default: 32
}

shouldCloseOnSelect

Para seletores de data e hora, shouldCloseOnSelect só é acionado em cliques de predefinições, não em cliques de data. Isso ocorre porque o usuário ainda precisa definir a hora após selecionar uma data.

resolvedTimeConfig

O valor de retorno resolvedTimeConfig contém a configuração de tempo totalmente resolvida com todos os padrões preenchidos. Use isso ao construir componentes de UI relacionados ao tempo para evitar re-computar os padrões.