본문으로 건너뛰기

useTimePicker

<TimePicker> 뒤의 훅. 커스텀 시간 UI (슬라이더, 휠, 자체 옵션 리스트)를 만들 때 사용합니다.

import { useTimePicker } from '@kalyx/react';

시그니처​

function useTimePicker(options?: UseTimePickerOptions): UseTimePickerReturn;

옵션​

필드타입기본값설명
valueISODateString | null-제어 값.
defaultValueISODateString-비제어 초기값.
onChange(value: ISODateString | null) => void-변경 콜백.
format'12h' | '24h''24h'시간 포맷.
stepnumber1분 간격.
withSecondsbooleanfalseTimePicker.Root 와 형태를 맞추려고 받아두지만 훅은 이 값을 읽지 않는다. currentTime 에는 항상 seconds 가 있고 setSecond 도 항상 동작한다. 초를 그릴지는 UI 가 정한다.

반환값​

필드타입설명
valueISODateString | null현재 값.
currentTimeTimeValue{ hours, minutes, seconds }.
setTime(partial: Partial<TimeValue>) => void부분 업데이트 병합.
setHour(hour: number) => void시 지정. 12h 모드에서는 1~12, 24h 모드에서는 0~23 을 받는다. 범위를 벗어나면 RangeError 가 발생한다.
setMinute(minute: number) => void분 지정.
setSecond(second: number) => void초 지정.
setPeriod(period: 'AM' | 'PM') => voidAM/PM 변경 (12h).
availableHoursnumber[]현재 포맷의 시 옵션.
availableMinutesnumber[]step으로 필터된 분.
format'12h' | '24h'해결된 포맷.
displayHournumber현재 포맷의 표시 시 (12h는 0/13 → 12/1).
period'AM' | 'PM' | null24h 모드에선 null.
pickerIdstringARIA용 안정 ID.

TimeValue​

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

예시: 스크롤 휠​

import { useTimePicker } from '@kalyx/react';

export function TimeWheel() {
  const {
    availableHours,
    availableMinutes,
    currentTime,
    setHour,
    setMinute,
  } = useTimePicker({ step: 15 });

  return (
    <div className="flex gap-2">
      <ul className="overflow-y-auto h-40">
        {availableHours.map((h) => (
          <li key={h}>
            <button
              aria-pressed={h === currentTime.hours}
              onClick={() => setHour(h)}>
              {String(h).padStart(2, '0')}
            </button>
          </li>
        ))}
      </ul>
      <ul className="overflow-y-auto h-40">
        {availableMinutes.map((m) => (
          <li key={m}>
            <button
              aria-pressed={m === currentTime.minutes}
              onClick={() => setMinute(m)}>
              {String(m).padStart(2, '0')}
            </button>
          </li>
        ))}
      </ul>
    </div>
  );
}

관련​