# Quantity Picker
URL: /components/quantity-picker
Source: https://github.com/daangn/seed-design/blob/dev/docs/content/components/quantity-picker.mdx

버튼으로 수치 값을 한 단계씩 늘리거나 줄일 수 있는 입력 컴포넌트입니다.

| Platform | Status |
| --- | --- |
| Figma | Done |
| [React](/react/components/quantity-picker) | Done |
| Lynx | Not Ready |
| iOS | Not Ready |
| Android | Not Ready |

## Anatomy

![Quantity Picker의 Anatomy 이미지. Decrement Button, Value Display, Increment Button으로 구성됩니다.](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/607e8c80-bb85-4572-9ae0-07fd9eb09f73)

Quantity Picker는 값을 한 단계 늘리는 Increment Button, 한 단계 줄이는 Decrement Button, 현재 값을 표시하는 Value Display 영역으로 구성됩니다.

## Properties

### Size

![Quantity Picker의 Size Property - Small, Medium, Large](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/1c60c1f3-de4b-463c-bf98-4c1a3040ade9)

Small, Medium, Large 세 가지 사이즈를 제공합니다. [Action Button](/components/action-button), [Text Input](/components/text-input) 등 다른 입력 요소와 함께 배치할 때는 사이즈를 맞춰 일관성을 유지합니다.

### Value State

![Quantity Picker의 Value State - Min, InRange, Max](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/29b8aa5f-3906-4e34-adf1-caecb0b8d97e)

입력 가능한 값의 범위를 prop으로 제한하여 범위를 벗어난 값을 입력하지 않도록 합니다.

- **Min**: 최소값에 도달해 Decrement가 불가능한 상태
- **InRange**: Increment / Decrement 모두 가능한 상태
- **Max**: 최대값에 도달해 Increment가 불가능한 상태

### State

![Quantity Picker의 State - Enabled, Disabled, Error](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/91a6b0e0-4932-442a-87ac-4e0b07695e6b)

Quantity Picker는 Enabled, Disabled, Error 상태를 가집니다.

- **Enabled**: 값 변경이 가능한 기본 상태
- **Disabled**: 값 변경이 불가능한 상태
- **Error**: 입력된 값이 허용 범위를 벗어난 상태

### Button State

![Quantity Picker의 Button State - Enabled, Hover/Pressed, Loading, Focused, Disabled](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/54ae9b81-4bd1-4fa0-b8c3-663167350018)

Decrement Button과 Increment Button은 각각 Enabled, Hover/Pressed, Loading, Focused, Disabled 다섯 가지 상태를 가집니다.

- **Enabled**: 선택 가능한 기본 상태
- **Hover/Pressed**: 마우스 오버, 클릭/터치 시 옅은 배경색 강조
- **Loading**: 수량 변경 요청에 대한 서버 응답을 기다리는 상태
- **Focused**: 키보드 포커스 시 포커스링 표시
- **Disabled**: 선택이 불가능한 상태

### Removable Property

![Quantity Picker의 Removable Property - Removable OFF, Removable ON](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/5aded461-6833-4e6b-82ef-8549bc01f709)

Removable 옵션을 활성화한 경우, 입력된 값이 최소값에 도달했을 때 Decrement 버튼을 Remove 버튼으로 교체합니다.

## Guidelines

### Quantity Picker 기본 사용하기

![장바구니 화면에서 Value Min과 Max 상태로 사용된 Quantity Picker 예시](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/e20aa2d3-2f71-471f-a35e-1c3f00083b06)

Quantity Picker는 장바구니, 상품 상세, 주문서 등 수량을 변경해야 하는 화면에서 사용합니다.

Quantity Picker는 Min·Max prop으로 입력 가능한 값의 범위를 제한합니다. 경계에 도달한 버튼은 자동으로 비활성화되어, 잘못된 값이 입력되는 것을 사전에 막습니다.

### Removable 활성화하기

![장바구니 화면에서 Removable OFF와 Removable ON을 비교한 Quantity Picker 예시](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/63b3fb9e-d86d-4cd7-8468-a09886417749)

Removable은 값이 최소값에 도달했을 때 Decrement 버튼을 Remove 버튼으로 교체하는 기능입니다. 값을 더 줄이는 동작이 곧 항목 삭제를 의미하는 맥락에서 사용합니다.

### Size 선택하기

![Small 사이즈 Quantity Picker를 사용한 예시](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/8346066a-5087-4455-a614-aff142fc6bd3)

![Medium 사이즈 Quantity Picker를 사용한 예시](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/2d0c6586-bbfd-40fa-9577-54152a0498f4)

[Action Button](/components/action-button), [Text Input](/components/text-input) 등 다른 입력 요소와 함께 배치할 때는 사이즈를 맞춰 일관성을 유지합니다.

### Quantity Picker 터치 영역

![Increment·Decrement 버튼에만 터치 영역이 적용된 Quantity Picker 예시](https://figma-alpha-api.s3.us-west-2.amazonaws.com/images/9917f376-78f4-43f5-93c0-b7ddd05bdd59)

Quantity Picker의 터치 영역은 양쪽 Increment·Decrement 버튼에 한정됩니다. Value Display는 터치에 반응하지 않습니다.

## Specification

### Quantity Picker

Component spec (JSON): /rootage/components/quantity-picker.json

### Quantity Picker Button

Component spec (JSON): /rootage/components/quantity-picker-button.json