useStandaloneTimePicker

열기/닫기 및 외부 클릭(click-outside) 동작으로 시간 상태를 관리합니다.

가져오기

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

사용법

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: "Select time",
});
return (
<div ref={picker.containerRef}>
<button onClick={picker.handleToggle}>
{picker.hasValue ? picker.displayValue : "Select time"}
</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>
{/* Hook up hour/minute controls */}
<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}>Clear</button>
<button onClick={picker.handleCancel}>Cancel</button>
<button onClick={picker.handleConfirm}>Confirm</button>
</div>
</div>
)}
</div>
);
}

옵션

옵션타입기본값설명
valueDate | null필수. 현재 시간을 나타내는 Date 객체 (시간 부분만 사용됩니다).
onChange(date: Date | null) => void필수. 시간이 확정될 때 호출됩니다.
timeTimeConfig{ precision: "minute", hourFormat: "24", minuteStep: 5, secondStep: 1 }타임 피커 설정.
localePartial<Locale>DEFAULT_LOCALE로케일 문자열을 재정의합니다.
displayFormatstring트리거 표시에 사용할 사용자 정의 포맷 문자열.
placeholderstring값이 선택되지 않았을 때의 플레이스홀더 텍스트.
openboolean제어되는 열림 상태.
initialOpenbooleanfalse초기 열림 상태 (비제어).
onOpenChange(open: boolean) => void열림 상태가 변경될 때의 콜백.
requiredbooleanfalsetrue일 경우, handleClear는 아무 작업도 수행하지 않습니다.
inlinebooleanfalse트리거/팝업 없이 항상 패널을 표시합니다.
namestring폼 제출을 위한 숨은 input의 이름.

반환 값

이름타입설명
isOpenboolean팝업이 현재 열려 있는지 여부.
handleOpen() => void팝업을 엽니다.
handleClose() => void팝업을 닫습니다.
handleToggle() => void팝업을 토글합니다.
tempHournumber현재 임시 시간 값.
tempMinutenumber현재 임시 분 값.
tempSecondnumber현재 임시 초 값.
tempPeriodTimePeriod현재 AM/PM 주기.
handleHourChange(hour: number) => void임시 시간을 업데이트합니다.
handleMinuteChange(minute: number) => void임시 분을 업데이트합니다.
handleSecondChange(second: number) => void임시 초를 업데이트합니다.
handlePeriodChange(period: TimePeriod) => voidAM/PM 주기를 업데이트합니다.
handleConfirm() => void임시 시간을 확정하고, onChange를 호출한 뒤, 팝업을 닫습니다.
handleCancel() => void원래 값으로 되돌리고 팝업을 닫습니다.
handleClear() => void값을 지우고 닫습니다. required가 true이면 아무 작업도 수행하지 않습니다.
displayValuestring트리거를 위한 포맷된 시간 문자열 (확정된 값).
timeDisplayValuestring패널을 위한 포맷된 시간 문자열 (임시 값).
hasValueboolean시간 값이 현재 설정되어 있는지 여부.
canConfirmboolean확인 버튼이 활성화되어야 하는지 여부.
localeLocale해결된 로케일 객체.
resolvedTimeConfigRequired<TimeConfig>완전히 해결된 시간 설정.
containerRefRefObject<HTMLDivElement | null>외부 컨테이너를 위한 Ref (외부 클릭 감지에 사용됨).
popupRefRefObject<HTMLDivElement | null>팝업 엘리먼트를 위한 Ref (외부 클릭 감지에 사용됨).
handleKeyDown(e: KeyboardEvent) => void키보드 핸들러 (취소하려면 Escape 키).

주요 동작

열기/닫기

팝업은 제어되거나 비제어될 수 있습니다. open prop이 제공되면, 훅은 이를 진실의 원천(source of truth)으로 사용합니다. 그렇지 않으면, 내부 상태가 사용되며 initialOpen이 시작 값이 됩니다.

외부 클릭

containerRefpopupRef 양쪽 모두의 바깥을 클릭하면 handleCancel이 트리거되어 원래 값으로 되돌리고 팝업을 닫습니다.

키보드

팝업이 열려 있는 동안 Escape 키를 누르면 handleCancel이 트리거됩니다.

인라인 모드

inlinetrue일 때, 패널은 항상 보이며 변경 사항이 즉시 적용됩니다 (자동 동기화). 열기/닫기 로직은 무시됩니다.

임시 상태 패턴

이 훅은 handleConfirm이 호출될 때만 커밋되는 임시 상태를 유지합니다:

  • handleConfirm — 임시 상태를 onChange에 쓰고 팝업을 닫습니다
  • handleCancel — 임시 상태를 현재 value로 되돌리고 닫습니다
  • handleClearonChange(null)를 호출하고 닫습니다

표시 값

  • displayValue — 커밋된 value의 포맷된 문자열 (트리거용)
  • timeDisplayValue — 임시 값의 포맷된 문자열 (패널용)