Skip to main content

useDateTimePicker

The headless hook behind <DateTimePicker>. One ISO string drives both the calendar and the time-of-day; selectDate preserves the time and setTime preserves the date.

:::info /headless entry Exported from @kalyx/react/headless (adapter-agnostic). See Date adapters & the /headless entry. :::

import { useDateTimePicker } from '@kalyx/react/headless';

Signature​

function useDateTimePicker(options?: UseDateTimePickerOptions): UseDateTimePickerReturn;

Options​

FieldTypeDefaultDescription
valueISODateString | null—Controlled datetime (date + time, UTC).
defaultValueISODateString—Uncontrolled initial datetime.
onChange(value: ISODateString | null) => void—Fires when the datetime changes.
disabledDisabledRule[][]Disable rules (applied to days).
weekStartsOn0 | 10Day the week starts on.
adapterDateAdapter—Date adapter (required on /headless).
displayTimezonestring—IANA zone. currentTime is reported in this zone. See Timezone.

Return​

FieldTypeDescription
valueISODateString | nullCurrent datetime.
isOpenbooleanPopover state.
open / close / toggle() => voidPopover controls.
selectDate(iso: ISODateString | null) => voidSet the date, preserving the time (does not close the popover).
setTime(partial: Partial<TimeValue>) => voidChange the time, preserving the date.
currentTimeTimeValueTime portion of the value (in displayTimezone when set).
viewMonthISODateStringFirst-day-of-visible-month.
setViewMonth(iso: ISODateString) => voidJump to a month.
calendarCalendarGrid6×7 grid of CalendarDays.
focusedDateISODateStringKeyboard-focused day.
setFocusedDate(iso: ISODateString) => voidMove focus.
previousMonth / nextMonth() => voidMonth navigation shorthands.
pickerIdstringStable ID for ARIA wiring.
adapterDateAdapterThe resolved adapter.

TimeValue​

type TimeValue = {
  hours: number;   // 0–23
  minutes: number; // 0–59
  seconds: number; // 0–59
};

Example​

import { useDateTimePicker } from '@kalyx/react/headless';
import { DateFnsAdapter } from '@kalyx/adapter-date-fns';

export function MiniDateTime() {
  const { value, currentTime, calendar, selectDate, setTime } =
    useDateTimePicker({ adapter: DateFnsAdapter, displayTimezone: 'Asia/Seoul' });

  return (
    <div>
      <div className="grid grid-cols-7">
        {calendar.flat().map((day) => (
          <button key={day.isoString} onClick={() => selectDate(day.isoString)}>
            {day.dayNumber}
          </button>
        ))}
      </div>
      <input
        type="number"
        value={currentTime.hours}
        onChange={(e) => setTime({ hours: Number(e.target.value) })}
      />
      <code>{value ?? 'null'}</code>
    </div>
  );
}