프리뷰 또는 이전 버전의 문서를 보고 있습니다.seed-design.io 방문
우리는 왜 디자인 엔지니어를 찾게 됐을까
Skip to Content
Lynx

Time Picker

휠을 스크롤하여 오전·오후, 시, 분을 선택하는 12시간제 시간 선택 컴포넌트입니다.

사용 가능 버전@seed-design/[email protected], @seed-design/[email protected]
Lynx 예제를 불러오는 중입니다.

Installation

npx @seed-design/cli@latest add ui:time-picker

Snippet은 Time Picker 컴포넌트와 컴포넌트 전용 props만 제공합니다. TimePickerValue, MinuteStep처럼 UI 구현과 독립적인 타입은 @seed-design/lynx-react에서 가져오세요.

import type { TimePickerValue } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";

CLI로 설치하면 Time Picker가 사용하는 ui:wheel-picker도 함께 설치됩니다.

Props

Prop

Type

disabled?boolean | undefined

모든 컬럼의 조작을 비활성화합니다.

Default

false

periodAccessibilityLabel?string | undefined

오전·오후 컬럼의 접근성 이름입니다. 지정하지 않으면 locale에 맞는 기본값을 사용합니다.

hourAccessibilityLabel?string | undefined

시 컬럼의 접근성 이름입니다. 지정하지 않으면 locale에 맞는 기본값을 사용합니다.

minuteAccessibilityLabel?string | undefined

분 컬럼의 접근성 이름입니다. 지정하지 않으면 locale에 맞는 기본값을 사용합니다.

value?TimePickerValue | undefined

제어할 시간 값입니다. 24시간 형식으로 전달합니다.

defaultValue?TimePickerValue | undefined

제어하지 않는 방식으로 사용할 때의 초기 시간 값입니다.

Default

{ hour: 0, minute: 0 }

onValueChange?((value: TimePickerValue) => void) | undefined

휠 스크롤이 선택 항목에 정착하여 값이 확정될 때 호출됩니다.

minuteStep?MinuteStep | undefined

분 컬럼의 선택 간격입니다. 간격에 맞지 않는 값은 가장 가까운 값으로 반올림합니다.

Default

5

locale?string | string[] | undefined

오전·오후 표기와 컬럼 순서를 결정할 locale입니다. Lynx에는 Intl이 없어 언어 하위 태그가 ko, ja, en인 locale만 구분합니다. 배열이면 지원하는 첫 locale을 쓰고, 지원하는 locale이 없으면 en을 씁니다.

Default

"ko-KR"

size, itemSize, visibleItemCount, scrollFogSize, readOnly를 제외한 Wheel Picker의 나머지 props는 내부 WheelPicker에 전달됩니다. ref도 내부 WheelPicker를 가리킵니다.

Examples

Basic

TimePicker는 휠 형태의 시간 선택 UI만 제공합니다. Trigger, Bottom Sheet, 확인·취소 버튼은 사용하는 화면에서 구성합니다.

import { TimePicker } from "@/components/ui/time-picker";

<TimePicker defaultValue={{ hour: 10, minute: 30 }} />

Controlled

value와 onValueChange를 사용하여 선택한 시간을 제어할 수 있습니다. onValueChange는 스크롤이 선택 항목에 정착하여 값이 확정되었을 때 Background Thread에서 호출됩니다.

현재는 12시간제 UI만 지원합니다. 다만 value, defaultValue, onValueChange에서 사용하는 TimePickerValue는 오전·오후를 별도 필드로 나누지 않고 24시간 형식으로 표현합니다.

interface TimePickerValue {
  /** 24시간 형식의 시입니다. 0 이상 23 이하의 정수입니다. */
  hour: number;
  /** 분입니다. 0 이상 59 이하의 정수입니다. */
  minute: number;
}

값을 지정하지 않으면 00:00에서 시작합니다. 선택된 시간이 없을 때 현재 시각에서 시작하려면 현재 시각의 hour와 minute을 defaultValue로 전달하세요.

유효한 값을 전달하세요

hour와 minute은 각각 유효한 범위의 정수여야 합니다. 유효하지 않은 value, defaultValue, minuteStep을 전달하면 RangeError가 발생합니다.

Lynx 예제를 불러오는 중입니다.

Use Case

Time Picker가 화면에서 차지하는 비중에 따라 레이아웃을 정합니다.

  • 시간 선택이 화면의 주된 작업이면 Inline을 사용합니다.
  • 폼의 시간 입력 필드에는 Bottom Sheet를 우선 검토합니다.

Bottom Sheet는 surface를 여는 trigger가 필요합니다. FieldButton처럼 현재 값을 표시하는 입력형 버튼과 합성할 수 있습니다. Inline의 확정은 화면의 액션 영역이, Bottom Sheet의 확정은 surface 안의 확인 버튼이 담당합니다.

Inline

글쓰기나 설정 플로우에서 시간 선택이 하나의 단계라면 화면 흐름 안에 Time Picker를 직접 배치합니다.

Lynx의 Time Picker 전체에는 접근성 이름을 연결할 수 없습니다. 화면 제목이 설명하는 맥락을 스크린 리더에도 전달하려면 periodAccessibilityLabel, hourAccessibilityLabel, minuteAccessibilityLabel에 그 맥락을 포함하세요.

Lynx 예제를 불러오는 중입니다.

Bottom Sheet

입력 필드를 누르면 화면 하단에서 Time Picker가 나타나도록 구성합니다. 사용자가 완료하기 전까지는 임시 값을 관리하고, 확인 버튼을 누를 때 입력 필드의 값으로 반영합니다.

Time Picker 위에서 시작한 세로 drag는 휠이 처리합니다. 시트를 drag로 움직이려면 handle이나 Time Picker 바깥 영역에서 시작하세요.

Lynx 예제를 불러오는 중입니다.

Date 객체와 함께 사용하기

TimePicker는 날짜나 시간대를 해석하지 않습니다. 애플리케이션에서 Date를 상태로 관리한다면 hour와 minute을 TimePickerValue로 변환하고, 변경된 시간을 기존 날짜에 반영하세요.

Lynx에는 Intl이 없어 Date.prototype.toLocaleString으로 지역화된 문자열을 만들 수 없습니다. 이 예제처럼 날짜를 직접 포맷하세요.

Lynx 예제를 불러오는 중입니다.

Minute Step

minuteStep은 1, 5, 10, 15, 30 중 하나를 사용할 수 있으며 기본값은 5입니다. 선택된 분이 간격에 맞지 않으면 가장 가까운 값으로 반올림합니다. 예를 들어 9시 13분은 minuteStep={5}에서 9시 15분으로 표시됩니다.

반올림은 시각 전체를 기준으로 계산하므로 시가 함께 바뀔 수 있습니다. 예를 들어 23시 59분은 minuteStep={5}에서 0시 0분이 됩니다. value를 제어하는 경우 정규화 자체로 onValueChange가 호출되지는 않습니다.

분 컬럼은 순환하지만 경계를 넘어도 시는 유지됩니다. 예를 들어 10시 55분에서 다음 분 항목인 00을 선택하면 10시 00분이 됩니다.

Lynx 예제를 불러오는 중입니다.

Disabled

disabled를 사용하면 모든 컬럼의 터치 조작과 값 변경을 막고 항목을 비활성 색으로 표시합니다.

Lynx 예제를 불러오는 중입니다.

Locale

locale에 따라 오전·오후 표기와 컬럼 순서가 달라집니다. 기본값은 "ko-KR"입니다.

Lynx에는 Intl이 없어 locale의 언어 하위 태그 ko, ja, en만 구분합니다. 예를 들어 "ko-KR"과 "ko"는 같은 결과를 보입니다. 그 밖의 언어는 en으로 표시합니다. 배열을 전달하면 지원하는 첫 locale을 사용합니다.

각 컬럼의 기본 접근성 이름도 locale에 따라 한국어, 영어 또는 일본어로 제공됩니다. 기본값 외의 언어가 필요하거나 맥락을 더 구체적으로 설명하려면 periodAccessibilityLabel, hourAccessibilityLabel, minuteAccessibilityLabel을 직접 지정합니다.

Lynx 예제를 불러오는 중입니다.

Accessibility

오전·오후, 시, 분 컬럼은 각각 접근성 요소로 제공됩니다. 각 컬럼은 role description spinbutton과 함께 컬럼의 접근성 이름과 현재 선택값을 알리며, disabled 상태도 전달합니다.

Time Picker 전체는 접근성 요소가 아니며 이름을 갖지 않습니다. 전체를 접근성 요소로 만들면 iOS에서 자식 컬럼이 가려질 수 있습니다. 맥락이 필요하면 각 컬럼의 접근성 이름에 포함하세요.

웹 버전과의 차이

  • 접근성 이름은 aria-label, periodAriaLabel, hourAriaLabel, minuteAriaLabel 대신 periodAccessibilityLabel, hourAccessibilityLabel, minuteAccessibilityLabel로 지정합니다. 전체에 대한 aria-label과 aria-labelledby는 없습니다.
  • 전체 컴포넌트에 group 역할과 기본 접근성 이름 "시간 선택"을 두지 않습니다. 각 컬럼만 접근성 요소입니다.
  • locale은 Intl 대신 언어 하위 태그 ko, ja, en만 비교합니다. 시는 locale과 관계없이 숫자 그대로, 분은 두 자리 숫자로 표시합니다.
  • onValueChange는 Background Thread에서 호출됩니다. 위치 계산과 애니메이션은 Main Thread에서 실행합니다.

Lynx 미지원 기능

  • 키보드 ArrowUp, ArrowDown, Home, End 조작과 Tab 컬럼 이동, 포커스 API는 지원하지 않습니다. 터치 드래그나 보이는 항목 탭으로 선택하세요.
  • 스크린 리더는 각 컬럼의 이름과 현재 값을 읽지만, 스와이프로 값을 올리고 내리는 조작(accessibility-actions 등)은 제공하지 않습니다. 시간을 직접 입력해야 하는 사용자를 위한 대체 입력은 화면에서 구성하세요.

Last updated on 2026. 11. 18.