# Time Picker
URL: /lynx/components/time-picker
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/lynx/components/time-picker.mdx
휠을 스크롤하여 오전·오후, 시, 분을 선택하는 12시간제 시간 선택 컴포넌트입니다.
사용 가능 버전: @seed-design/lynx-react@1.4.0, @seed-design/lynx-css@1.4.0
## Preview
```tsx
import { Box } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
export default function TimePickerPreview() {
return (
);
}
```
## Installation
- npm: npx @seed-design/cli@latest add ui:time-picker
- pnpm: pnpm dlx @seed-design/cli@latest add ui:time-picker
- yarn: yarn dlx @seed-design/cli@latest add ui:time-picker
- bun: bun x @seed-design/cli@latest add ui:time-picker
Snippet은 Time Picker 컴포넌트와 컴포넌트 전용 props만 제공합니다. `TimePickerValue`, `MinuteStep`처럼 UI 구현과 독립적인 타입은 `@seed-design/lynx-react`에서 가져오세요.
```tsx
import type { TimePickerValue } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
```
CLI로 설치하면 Time Picker가 사용하는 `ui:wheel-picker`도 함께 설치됩니다.
## Props
`size`, `itemSize`, `visibleItemCount`, `scrollFogSize`, `readOnly`를 제외한 Wheel Picker의 나머지 props는 내부 `WheelPicker`에 전달됩니다. `ref`도 내부 `WheelPicker`를 가리킵니다.
## Examples
### Basic
`TimePicker`는 휠 형태의 시간 선택 UI만 제공합니다. Trigger, Bottom Sheet, 확인·취소 버튼은 사용하는 화면에서 구성합니다.
```tsx
import { TimePicker } from "@/components/ui/time-picker";
```
### Controlled
`value`와 `onValueChange`를 사용하여 선택한 시간을 제어할 수 있습니다. `onValueChange`는 스크롤이 선택 항목에 정착하여 값이 확정되었을 때 Background Thread에서 호출됩니다.
현재는 12시간제 UI만 지원합니다. 다만 `value`, `defaultValue`, `onValueChange`에서 사용하는 `TimePickerValue`는 오전·오후를 별도 필드로 나누지 않고 24시간 형식으로 표현합니다.
```ts
interface TimePickerValue {
/** 24시간 형식의 시입니다. 0 이상 23 이하의 정수입니다. */
hour: number;
/** 분입니다. 0 이상 59 이하의 정수입니다. */
minute: number;
}
```
값을 지정하지 않으면 `00:00`에서 시작합니다. 선택된 시간이 없을 때 현재 시각에서 시작하려면 현재 시각의 `hour`와 `minute`을 `defaultValue`로 전달하세요.
`hour`와 `minute`은 각각 유효한 범위의 정수여야 합니다. 유효하지 않은 `value`, `defaultValue`, `minuteStep`을 전달하면 `RangeError`가 발생합니다.
```tsx
import * as React from "@lynx-js/react";
import { Box, Text, type TimePickerValue, VStack } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
export default function TimePickerControlled() {
const [value, setValue] = React.useState({ hour: 10, minute: 30 });
return (
{String(value.hour).padStart(2, "0")}:{String(value.minute).padStart(2, "0")}
);
}
```
### 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`에 그 맥락을 포함하세요.
```tsx
import * as React from "@lynx-js/react";
import { ActionButton, HStack, Text, type TimePickerValue, VStack } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
function formatTime({ hour, minute }: TimePickerValue) {
const period = hour < 12 ? "오전" : "오후";
const displayHour = hour % 12 || 12;
return `${period} ${displayHour}:${String(minute).padStart(2, "0")}`;
}
export default function TimePickerInline() {
const [value, setValue] = React.useState({ hour: 10, minute: 30 });
const [savedValue, setSavedValue] = React.useState(value);
return (
영업 시작 시간
현재 설정: {formatTime(savedValue)}
{
"background only";
setSavedValue(value);
}}
>
완료
);
}
```
#### Bottom Sheet
입력 필드를 누르면 화면 하단에서 Time Picker가 나타나도록 구성합니다. 사용자가 완료하기 전까지는 임시 값을 관리하고, 확인 버튼을 누를 때 입력 필드의 값으로 반영합니다.
Time Picker 위에서 시작한 세로 drag는 휠이 처리합니다. 시트를 drag로 움직이려면 handle이나 Time Picker 바깥 영역에서 시작하세요.
```tsx
import * as React from "@lynx-js/react";
import { ActionButton, Box, type TimePickerValue } from "@seed-design/lynx-react";
import {
BottomSheetBody,
BottomSheetContent,
BottomSheetFooter,
BottomSheetRoot,
} from "@/components/ui/bottom-sheet";
import { FieldButton, FieldButtonValue } from "@/components/ui/field-button";
import { TimePicker } from "@/components/ui/time-picker";
function formatTime({ hour, minute }: TimePickerValue) {
const period = hour < 12 ? "오전" : "오후";
const displayHour = hour % 12 || 12;
return `${period} ${displayHour}:${String(minute).padStart(2, "0")}`;
}
export default function TimePickerBottomSheet() {
const [open, setOpen] = React.useState(false);
const [value, setValue] = React.useState({ hour: 10, minute: 30 });
const [draft, setDraft] = React.useState(value);
const handleOpenChange = (nextOpen: boolean) => {
"background only";
if (nextOpen) setDraft(value);
setOpen(nextOpen);
};
return (
{
"background only";
handleOpenChange(true);
},
}}
>
{formatTime(value)}
{
"background only";
setValue(draft);
setOpen(false);
}}
>
완료
);
}
```
### Date 객체와 함께 사용하기
`TimePicker`는 날짜나 시간대를 해석하지 않습니다. 애플리케이션에서 `Date`를 상태로 관리한다면 `hour`와 `minute`을 `TimePickerValue`로 변환하고, 변경된 시간을 기존 날짜에 반영하세요.
Lynx에는 `Intl`이 없어 `Date.prototype.toLocaleString`으로 지역화된 문자열을 만들 수 없습니다. 이 예제처럼 날짜를 직접 포맷하세요.
```tsx
import * as React from "@lynx-js/react";
import { Box, Text, type TimePickerValue, VStack } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
// Lynx에는 `Intl`이 없어 `toLocaleString("ko-KR")` 대신 직접 포맷합니다.
function formatDate(date: Date) {
const hour = date.getHours();
const period = hour < 12 ? "오전" : "오후";
const displayHour = hour % 12 || 12;
const minute = String(date.getMinutes()).padStart(2, "0");
const second = String(date.getSeconds()).padStart(2, "0");
return `${date.getFullYear()}. ${date.getMonth() + 1}. ${date.getDate()}. ${period} ${displayHour}:${minute}:${second}`;
}
export default function TimePickerDateValue() {
const [date, setDate] = React.useState(() => new Date(2026, 6, 28, 13, 30));
const value: TimePickerValue = {
hour: date.getHours(),
minute: date.getMinutes(),
};
const handleValueChange = ({ hour, minute }: TimePickerValue) => {
"background only";
setDate((currentDate) => {
const nextDate = new Date(currentDate);
nextDate.setHours(hour, minute, 0, 0);
return nextDate;
});
};
return (
{formatDate(date)}
);
}
```
### 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분이 됩니다.
```tsx
import { Box } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
export default function TimePickerMinuteStep() {
return (
);
}
```
### Disabled
`disabled`를 사용하면 모든 컬럼의 터치 조작과 값 변경을 막고 항목을 비활성 색으로 표시합니다.
```tsx
import { Box } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
export default function TimePickerDisabled() {
return (
);
}
```
### Locale
`locale`에 따라 오전·오후 표기와 컬럼 순서가 달라집니다. 기본값은 `"ko-KR"`입니다.
Lynx에는 `Intl`이 없어 locale의 언어 하위 태그 `ko`, `ja`, `en`만 구분합니다. 예를 들어 `"ko-KR"`과 `"ko"`는 같은 결과를 보입니다. 그 밖의 언어는 `en`으로 표시합니다. 배열을 전달하면 지원하는 첫 locale을 사용합니다.
각 컬럼의 기본 접근성 이름도 `locale`에 따라 한국어, 영어 또는 일본어로 제공됩니다. 기본값 외의 언어가 필요하거나 맥락을 더 구체적으로 설명하려면 `periodAccessibilityLabel`, `hourAccessibilityLabel`, `minuteAccessibilityLabel`을 직접 지정합니다.
```tsx
import { Box } from "@seed-design/lynx-react";
import { TimePicker } from "@/components/ui/time-picker";
export default function TimePickerLocalization() {
return (
);
}
```
### 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` 등)은 제공하지 않습니다. 시간을 직접 입력해야 하는 사용자를 위한 대체 입력은 화면에서 구성하세요.