TimePicker

세그먼트 + 드롭다운으로 시간을 선택하는 기본 컴포넌트

개요

Foundation TimePicker는 Popover 기반의 시간 선택 컴포넌트입니다. 하나의 input에 시·분(·초)를 입력하고 드롭다운으로 선택합니다. AM/PM은 좌측 버튼으로 제공되며, iCignal 레이어에서 FormItem(레이블/에러/필수 표시) 확장을 제공합니다.

주요 특징

• ✅ 단일 input + 드롭다운: 시·분·초를 하나의 input에서 입력하거나 드롭다운에서 선택
• ✅ 자동 마스킹: 숫자만 타이핑해도 HH:MM[:SS] 형식으로 콜론 자동 삽입
• ✅ 12 / 24시간제: use12Hour prop으로 전환 (기본 12시간제)
• ✅ AM/PM 라벨 커스터마이즈: amLabel·pmLabel로 다국어 텍스트 지원 (기본 AM/PM)
• ✅ 초 선택: showSeconds로 초 세그먼트 및 컬럼 추가
• ✅ 간격 설정: minuteStep, secondStep으로 선택 간격 제어
• ✅ 제어/비제어: value/defaultValue 모두 지원
• ✅ 상태: disabled, readOnly, 포커스 링
• ✅ 다양한 크기: xs, sm, md, lg, xl
• ✅ 디자인 토큰: --input-* 토큰 상속, 테마 커스터마이징 지원

Sizes

<TimePicker size="xs" />
<TimePicker size="sm" />
<TimePicker size="md" />
<TimePicker size="lg" />
<TimePicker size="xl" />

사용 예시

기본 사용

각 세그먼트(오전/오후 · 시 · 분)를 클릭하면 드롭다운이 열리고 값을 선택합니다. 우측 아이콘 버튼은 시 세그먼트 드롭다운의 단축 토글입니다.

const [time, setTime] = useState<Date | undefined>()
 
<TimePicker value={time} onChange={setTime} width={200} />

기본값 설정

defaultValue로 초기값을 지정할 수 있습니다.

<TimePicker defaultValue={new Date(2025, 0, 1, 14, 30)} width={200} />

12시간제 / 24시간제

기본은 12시간제(AM/PM)입니다. use12Hour={false}로 24시간제로 전환하면 오전/오후 세그먼트가 사라집니다.

{/* 12시간제 (기본) */}
<TimePicker use12Hour defaultValue={new Date(2025, 0, 1, 9, 15)} />
 
{/* 24시간제 */}
<TimePicker use12Hour={false} defaultValue={new Date(2025, 0, 1, 21, 45)} />

AM / PM 라벨 커스터마이즈

amLabel / pmLabel prop으로 오전·오후 표시 텍스트를 변경할 수 있습니다. 기본값은 "AM" / "PM"입니다. 다국어 환경에서 한글·일본어·중국어 등으로 손쉽게 대체할 수 있습니다.

{/* 기본값 (AM/PM) */}
<TimePicker defaultValue={new Date(2025, 0, 1, 9, 0)} />
 
{/* 한글 */}
<TimePicker amLabel="오전" pmLabel="오후" defaultValue={new Date(2025, 0, 1, 14, 0)} />
 
{/* 일본어 */}
<TimePicker amLabel="午前" pmLabel="午後" defaultValue={new Date(2025, 0, 1, 14, 0)} />

초 표시

showSeconds로 초 세그먼트와 드롭다운 컬럼을 추가합니다.

<TimePicker showSeconds defaultValue={new Date(2025, 0, 1, 10, 30, 45)} />

분 / 초 간격 설정

minuteStep / secondStep으로 드롭다운 옵션 간격을 조절합니다.

<TimePicker minuteStep={5} />
<TimePicker minuteStep={15} />
<TimePicker showSeconds secondStep={10} />

너비 제어

width로 트리거 너비를 고정합니다.

<TimePicker width={160} />
<TimePicker width={220} showSeconds />

비활성화 / 읽기 전용

disabled는 전체 트리거를 비활성화하고, readOnly는 값을 유지한 채 선택만 차단합니다.

<TimePicker disabled defaultValue={new Date(2025, 0, 1, 12, 0)} />
<TimePicker readOnly defaultValue={new Date(2025, 0, 1, 9, 30)} />

키보드 직접 입력 (Key-in)

시·분·초는 하나의 <input type="text" inputMode="numeric"> 필드로 통합되어 있습니다. 숫자만 타이핑하면 HH:MM[:SS] 형식으로 콜론이 자동 삽입되며, 최대 자릿수(4 또는 6)를 채우면 즉시 commit됩니다. 부분 입력 상태에서는 Tab / blur 시점에 검증 후 commit되며, 유효하지 않으면 기존 값이 유지됩니다. 붙여넣기 · 전체 선택 · 백스페이스 같은 브라우저 기본 텍스트 편집이 모두 동작합니다. AM/PM은 별도 버튼으로 좌측에 유지되며 A/P 키 또는 클릭으로 지정합니다.

{/* 12시간제: AM/PM 버튼 + 단일 input (HH:MM) */}
<TimePicker width={200} />
 
{/* 24시간제 + 초: 단일 input (HH:MM:SS) */}
<TimePicker width={220} use12Hour={false} showSeconds />

키보드 내비게이션

API Reference

Props

Events

기본 사용법

import { TimePicker } from "@vortex/ui-foundation"
 
<TimePicker />
<TimePicker use12Hour={false} showSeconds />
<TimePicker minuteStep={15} defaultValue={new Date()} />

접근성

권장 사항

• ✅ 키보드: Tab으로 세그먼트 및 아이콘 버튼 이동, ←/→로 세그먼트 간 이동
• ✅ 실제 <input> 기반 텍스트 입력 — 붙여넣기 / IME / 스크린리더 등 표준 입력 경로 지원
• ✅ ↑/↓로 step 단위 증감, 경계에서 자동 wrap
• ✅ 각 세그먼트는 aria-label을 포함하는 버튼으로 제공
• ✅ 드롭다운은 Popover 기반으로 포커스 트랩 및 Esc 닫기 지원
• ❌ 레이블/설명 없이 단독 사용은 iCignal 래퍼 사용 권장

관련 컴포넌트

• TimePicker (iCignal): FormItem 통합 래퍼 (label, required, error 등)
• DatePicker (Foundation): 날짜 선택
• Input (Foundation): 일반 텍스트 입력