TimePicker
세그먼트 + 드롭다운으로 시간을 선택하는 폼 컴포넌트
개요
iCignal TimePicker는 Foundation TimePicker를 FormItem으로 래핑하여 레이블, 필수값, 설명, 에러 메시지를 통합 제공합니다. 폼 내에서 시간 입력 필드로 사용할 수 있습니다.
주요 특징
- ✅ 필수값 표시: Label 좌측에 *(Asterisk) 표시
- ✅ 세그먼트 선택: 오전/오후 · 시 · 분 · 초 개별 선택
- ✅ 키보드 직접 입력(Key-in): 시·분·초는 실제
<input>필드로 텍스트 타이핑 지원 - ✅ 12 / 24시간제:
use12Hourprop으로 전환 - ✅ 초 선택:
showSeconds로 초까지 선택 - ✅ 간격 설정:
minuteStep,secondStep - ✅ 오류 상태:
error로 메시지 표시 및 포커스 링 강조 - ✅ 읽기 전용 / 비활성화:
readOnly,disabled - ✅ 다양한 크기: xs, sm, md, lg, xl
- ✅ FormItem 통합: 레이블, 설명, 에러 메시지
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Sizes
Preview
States
Preview
24시간 형식 · 15분 단위
사용 예시
필수값 표시
필수 입력 항목은 Label 좌측에 *(Asterisk)를 표시합니다.
Preview
12시간제 / 24시간제
기본값은 12시간제(AM/PM)이며, use12Hour={false}로 24시간제로 전환할 수 있습니다.
Preview
초 표시
showSeconds로 초까지 선택할 수 있는 세그먼트와 컬럼이 추가됩니다.
Preview
분 / 초 간격 설정
minuteStep, secondStep으로 드롭다운 옵션 간격을 조절합니다. 예약 시간처럼 특정 단위만 허용할 때 유용합니다.
Preview
오류 상태 표시
error prop으로 오류 메시지를 표시합니다. 포커스 링이 에러 색상으로 강조됩니다.
Preview
레이블 레이아웃
orientation="vertical"로 레이블을 상단에 배치할 수 있습니다.
Preview
예시 1: 회의 예약 시간
15분 단위로 회의 시작/종료 시각을 예약합니다.
Preview
예시 2: 배치 작업 스케줄
초 단위까지 정밀하게 스케줄을 설정합니다.
Preview
초 단위 정밀 스케줄
키보드 직접 입력 (Key-in)
시·분·초 세그먼트는 실제 <input type="text" inputMode="numeric"> 필드로, 일반 텍스트 입력처럼 숫자를 직접 타이핑할 수 있습니다. 붙여넣기 · 전체 선택 · 백스페이스 같은 브라우저 기본 텍스트 편집이 모두 동작합니다. 두 자리를 모두 채우면 해당 세그먼트를 확정하고 자동으로 다음 세그먼트로 포커스가 이동합니다. 한 자리만 입력하고 넘기려면 Tab / → / Enter를 누르거나 다른 곳을 클릭하면 됩니다.
Preview
키보드 내비게이션
| 키 | 동작 |
|---|---|
0 – 9 | 시/분/초 input에 실제 텍스트 타이핑 (두 자리 채우면 자동 이동) |
↑ / ↓ | 현재 세그먼트 값 증감 (step 반영, 경계에서 wrap) |
← / → | 이전/다음 세그먼트로 포커스 이동 |
A / P | AM / PM 지정 (period 세그먼트에서) |
Backspace | input의 문자 삭제, 비어있을 때 누르면 이전 세그먼트로 이동 |
Enter / Space | 드롭다운 토글 |
Esc | 열린 드롭다운 닫기 |
Tab / Shift+Tab | 다음/이전 포커스 가능 요소로 이동 (기본 동작) |
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | Date | - | 선택된 시간 (제어 컴포넌트) |
defaultValue | Date | - | 초기 시간 |
use12Hour | boolean | true | 12시간제(AM/PM) 사용 여부 |
showSeconds | boolean | false | 초 세그먼트 표시 여부 |
minuteStep | number | 1 | 분 드롭다운 간격 |
secondStep | number | 1 | 초 드롭다운 간격 |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 컴포넌트 크기 |
width | string | number | - | 트리거 너비 |
disabled | boolean | false | 비활성화 여부 |
readOnly | boolean | false | 읽기 전용 여부 |
label | string | - | 필드 레이블 |
labelWidth | string | number | - | 레이블 너비 |
labelAlign | "start" | "center" | "end" | - | 레이블 가로 정렬 |
labelVerticalAlign | "start" | "center" | "end" | - | 레이블 세로 정렬 |
align | "start" | "center" | "end" | - | 필드 영역 정렬 |
required | boolean | false | 필수 여부 (* 표시) |
orientation | "horizontal" | "vertical" | "horizontal" | 레이블-필드 배치 방향 |
description | string | - | 설명 텍스트 |
error | string | - | 에러 메시지 |
className | string | - | FormItem 래퍼에 적용할 CSS 클래스 |
inputClassName | string | - | TimePicker 트리거에 적용할 클래스 |
Events
| Event | Type | Description |
|---|---|---|
onChange | (value: Date | undefined) => void | 값 변경 시 호출 |
기본 사용법
import { TimePicker } from "@vortex/ui-icignal"
// 기본
<TimePicker label="시간" />
// 24시간제 + 15분 단위
<TimePicker label="시작" use12Hour={false} minuteStep={15} />
// 초 포함 + 필수
<TimePicker label="실행 시각" showSeconds required />접근성
ARIA 속성
<TimePicker label="시작 시각" required />권장 사항
- ✅
label로 시간 선택 목적 전달 - ✅
description/error로 맥락과 유효성 안내 - ✅ 키보드: Tab으로 세그먼트·아이콘 버튼 이동, ←/→로 세그먼트 간 이동, Esc로 드롭다운 닫기
- ✅ 실제
<input>기반 텍스트 입력 — 붙여넣기 / IME / 스크린리더 등 표준 입력 경로 지원 - ✅ ↑/↓로
step단위 증감, 경계에서 자동 wrap - ❌ 레이블 없이 단독 사용 지양
관련 컴포넌트
- TimePicker (Foundation): 기본 TimePicker
- DatePicker: 날짜 선택
- Input: 텍스트 입력
- InputNumber: 숫자 입력