정수 단위의 수량을 늘리거나 줄일 때 사용하는 컴포넌트입니다.
import "./styles" ; import { QuantityPicker } from "@/components/ui/quantity-picker" ; export default function Example () { return < QuantityPicker min = { 1 } max = { 99 } defaultValue = { 1 } accessibility-label = "상품 수량" />; }
npx @seed-design/cli@latest add ui:quantity-picker pnpm dlx @seed-design/cli@latest add ui:quantity-picker yarn dlx @seed-design/cli@latest add ui:quantity-picker bun x @seed-design/cli@latest add ui:quantity-picker 의존성 설치
npm install @karrotmarket/lynx-monochrome-icon @seed-design/lynx-react yarn add @karrotmarket/lynx-monochrome-icon @seed-design/lynx-react pnpm add @karrotmarket/lynx-monochrome-icon @seed-design/lynx-react bun add @karrotmarket/lynx-monochrome-icon @seed-design/lynx-react 아래 코드를 복사 후 붙여넣고 사용하세요 /** * @file ui:quantity-picker * @requires @seed-design/lynx-react@^1.0.0 * @requires @seed-design/lynx-css@^1.0.0 * @requires @karrotmarket/lynx-monochrome-icon@>=1.20.0 <2.0.0 **/ import IconMinusLine from "@karrotmarket/lynx-monochrome-icon/IconMinusLine" ; import IconPlusLine from "@karrotmarket/lynx-monochrome-icon/IconPlusLine" ; import IconTrashcanLine from "@karrotmarket/lynx-monochrome-icon/IconTrashcanLine" ; import * as React from "@lynx-js/react" ; import { ProgressCircle as SeedProgressCircle, QuantityPicker as SeedQuantityPicker, } from "@seed-design/lynx-react" ; function resolveProgressCircleProps ( size : SeedQuantityPicker . RootProps [ "size" ], ) : Pick < SeedProgressCircle . RootProps , "size" | "style" > { switch (size) { case "small" : return { size: "16" }; case "large" : return { size: "24" , style: { transform: "scale(0.9166667)" } }; default : return { size: "18" }; } } type DistributiveOmit < T , K extends PropertyKey > = T extends unknown ? Omit < T , K > : never ; export type QuantityPickerProps = DistributiveOmit < SeedQuantityPicker . RootProps , "children" | "removeAccessibilityLabel" > & { /** * Remove 버튼의 접근성 이름입니다. * @default " 상품 삭제 " */ removeAccessibilityLabel ?: SeedQuantityPicker . RootProps [ "removeAccessibilityLabel" ]; /** * Decrement 버튼의 접근성 이름입니다. * @default " 수량 줄이기 " */ decrementAccessibilityLabel ?: string ; /** * Increment 버튼의 접근성 이름입니다. * @default " 수량 늘리기 " */ incrementAccessibilityLabel ?: string ; /** * Decrement 버튼에 표시할 아이콘입니다. * @default <IconMinusLine /> */ decrementIcon ?: React . ReactNode ; /** * Increment 버튼에 표시할 아이콘입니다. * @default <IconPlusLine /> */ incrementIcon ?: React . ReactNode ; /** * Remove 버튼에 표시할 아이콘입니다. * @default <IconTrashcanLine /> */ removeIcon ?: React . ReactNode ; /** * loading 상태일 때 버튼에 표시할 요소입니다. * @default <ProgressCircle.Root><ProgressCircle.Track /><ProgressCircle.Range /></ProgressCircle.Root> */ loadingIndicator ?: React . ReactNode ; }; /** * @see https://seed-design.io/lynx/components/quantity-picker */ export const QuantityPicker = React. forwardRef < unknown , QuantityPickerProps >( ( { decrementAccessibilityLabel = "수량 줄이기" , incrementAccessibilityLabel = "수량 늘리기" , removeAccessibilityLabel = "상품 삭제" , decrementIcon = < IconMinusLine />, incrementIcon = < IconPlusLine />, removeIcon = < IconTrashcanLine />, loadingIndicator, size, ... rootProps }, ref, ) => { const resolvedLoadingIndicator = loadingIndicator === undefined ? ( < SeedProgressCircle.Root { ... resolveProgressCircleProps (size)} tone = "inherit" > < SeedProgressCircle.Track /> < SeedProgressCircle.Range /> </ SeedProgressCircle.Root > ) : ( loadingIndicator ); const resolvedRootProps : SeedQuantityPicker . RootProps = rootProps.removable ? { ... rootProps, removable: true , removeAccessibilityLabel, } : { ... rootProps, removable: false , removeAccessibilityLabel, }; return ( < SeedQuantityPicker.Root ref = {ref} size = {size} { ... resolvedRootProps}> < SeedQuantityPicker.DecrementButton accessibility-label = {decrementAccessibilityLabel} icon = {decrementIcon} loadingIndicator = {resolvedLoadingIndicator} removeIcon = {removeIcon} /> < SeedQuantityPicker.ValueDisplay /> < SeedQuantityPicker.IncrementButton accessibility-label = {incrementAccessibilityLabel} icon = {incrementIcon} loadingIndicator = {resolvedLoadingIndicator} /> </ SeedQuantityPicker.Root > ); }, ); QuantityPicker.displayName = "QuantityPicker" ; /** * This file is a snippet from SEED Design, helping you get started quickly with @seed-design/* packages. * You can extend this snippet however you want. */ Registry의 QuantityPicker는 수량 선택에 필요한 감소 버튼, 값, 증가 버튼을 함께 제공합니다.
getValueText?QuantityPickerGetValueText | undefined
layout?"fill" | "hug" | undefined
size?"small" | "medium" | "large" | undefined
min과 max는 필수이며 안전한 정수여야 합니다. step의 기본값은 1이고, defaultValue를 생략하면 min에서 시작합니다. value와 onValueChange를 함께 사용하면 값을 외부 상태로 제어할 수 있습니다.
layout="hug"는 콘텐츠에 맞는 너비를 유지합니다. 부모가 Flex 레이아웃이고 남은 공간을 채워야 한다면 layout="fill"을 사용하세요. 양쪽 버튼 크기는 유지되고 Value Display 영역만 늘어납니다.
import "./styles" ; import { QuantityPicker } from "@/components/ui/quantity-picker" ; export default function Example () { return ( < view className = "quantity-picker-example quantity-picker-layout-host" > < text className = "quantity-picker-example-title" >Layout</ text > < view className = "quantity-picker-layout-row" > < text className = "quantity-picker-layout-label" >Hug (기본)</ text > < view className = "quantity-picker-example-controls" > < QuantityPicker layout = "hug" min = { 1 } max = { 99 } defaultValue = { 1 } accessibility-label = "Hug 상품 수량" /> </ view > </ view > < view className = "quantity-picker-layout-row" > < text className = "quantity-picker-layout-label" >Fill</ text > < view className = "quantity-picker-example-controls" > < QuantityPicker layout = "fill" min = { 1 } max = { 99 } defaultValue = { 1 } accessibility-label = "Fill 상품 수량" /> </ view > </ view > </ view > ); } 이 예제에서 사용하는 Quantity Picker recipe는 display: grid를 사용합니다. Android/iOS Lynx engine 2.1 이상과 HarmonyOS Lynx engine 3.4 이상에서 호환됩니다.
getValueText를 사용하면 표시되는 수량에 단위나 보조 설명을 덧붙일 수 있습니다. 반환한 값은 Value Display와 접근성 값에 사용할 표시 텍스트이며, 내부 수량 상태나 증감 단위에는 영향을 주지 않습니다.
import "./styles" ; import { QuantityPicker } from "@/components/ui/quantity-picker" ; export default function Example () { return ( < view className = "quantity-picker-example" > < text className = "quantity-picker-example-title" >Value text</ text > < view className = "quantity-picker-example-controls" > < QuantityPicker min = { 1 } max = { 99 } defaultValue = { 1 } accessibility-label = "상품 수량" getValueText = {( valueText : string ) => `${ valueText }개` } /> </ view > </ view > ); } value와 onValueChange를 사용해 수량 상태를 앱의 상태로 제어할 수 있습니다. 변경 콜백에서 새 숫자를 저장하고, 저장한 값을 다시 value로 전달하세요.
import "./styles" ; import { useState } from "@lynx-js/react" ; import { QuantityPicker } from "@/components/ui/quantity-picker" ; export default function Example () { const [ quantity , setQuantity ] = useState ( 2 ); function handleValueChange ( nextQuantity : number ) { "background only" ; setQuantity (nextQuantity); } return ( < view className = "quantity-picker-example" > < text className = "quantity-picker-example-title" >Controlled</ text > < QuantityPicker min = { 1 } max = { 99 } value = {quantity} onValueChange = {handleValueChange} accessibility-label = "상품 수량" /> < text className = "quantity-picker-example-status" >현재 수량: {quantity}개</ text > </ view > ); } removable을 사용하면 값이 min에 도달했을 때 Decrement 버튼이 Remove 버튼으로 전환됩니다. 이때 Decrement를 누르면 수량을 변경하지 않고 onRemove만 호출합니다. 삭제나 목록에서 제거하는 동작은 onRemove에서 처리하세요.
import "./styles" ; import { useState } from "@lynx-js/react" ; import { ActionButton, VStack } from "@seed-design/lynx-react" ; import { QuantityPicker } from "@/components/ui/quantity-picker" ; export default function Example () { const [ removed , setRemoved ] = useState ( false ); function handleRemove () { "background only" ; setRemoved ( true ); } function handleRestore () { "background only" ; setRemoved ( false ); } return ( < view className = "quantity-picker-example" > < text className = "quantity-picker-example-title" >Removable</ text > {removed ? ( < VStack gap = "x4" align = "center" > < text className = "quantity-picker-example-status" >상품을 삭제했습니다.</ text > < view className = "quantity-picker-example-controls" > < ActionButton className = "quantity-picker-example-control" variant = "neutralWeak" bindtap = {handleRestore} > 되돌리기 </ ActionButton > </ view > </ VStack > ) : ( <> < view className = "quantity-picker-example-controls" > < QuantityPicker min = { 1 } max = { 99 } defaultValue = { 1 } removable removeAccessibilityLabel = "상품 삭제" accessibility-label = "상품 수량" onRemove = {handleRemove} /> </ view > < text className = "quantity-picker-example-status" > 최솟값에서 감소 버튼을 누르면 수량 선택기가 제거됩니다. </ text > </> )} </ view > ); } loading으로 모든 action 또는 특정 action의 실행을 일시적으로 막고 loading indicator를 표시할 수 있습니다. loading={true}는 Decrement와 Increment 모두에 적용되며, loading={{ increment: true }}처럼 객체를 전달하면 해당 action만 막습니다.
import "./styles" ; import { useState } from "@lynx-js/react" ; import { ActionButton } from "@seed-design/lynx-react" ; import { QuantityPicker } from "@/components/ui/quantity-picker" ; export default function Example () { const [ decrementLoading , setDecrementLoading ] = useState ( false ); const [ incrementLoading , setIncrementLoading ] = useState ( false ); const allLoading = decrementLoading && incrementLoading; function toggleAllLoading () { "background only" ; const nextLoading = ! allLoading; setDecrementLoading (nextLoading); setIncrementLoading (nextLoading); } function toggleDecrementLoading () { "background only" ; setDecrementLoading (( current ) => ! current); } function toggleIncrementLoading () { "background only" ; setIncrementLoading (( current ) => ! current); } return ( < view className = "quantity-picker-example" > < text className = "quantity-picker-example-title" >Loading</ text > < QuantityPicker min = { 1 } max = { 99 } defaultValue = { 2 } loading = { allLoading ? true : { decrement: decrementLoading, increment: incrementLoading, } } accessibility-label = "상품 수량" /> < view className = "quantity-picker-example-controls" > < ActionButton className = "quantity-picker-example-control" variant = "neutralWeak" bindtap = {toggleAllLoading} > 전체 {allLoading ? "끄기" : "켜기" } </ ActionButton > < ActionButton className = "quantity-picker-example-control" variant = "neutralWeak" bindtap = {toggleDecrementLoading} > 감소 {decrementLoading ? "끄기" : "켜기" } </ ActionButton > < ActionButton className = "quantity-picker-example-control" variant = "neutralWeak" bindtap = {toggleIncrementLoading} > 증가 {incrementLoading ? "끄기" : "켜기" } </ ActionButton > </ view > < text className = "quantity-picker-example-status" > 감소: {decrementLoading ? "loading" : "준비" } · 증가:{ " " } {incrementLoading ? "loading" : "준비" } </ text > </ view > ); } disabled, readOnly, loading은 모두 action을 실행하지 못하게 합니다. disabled는 두 action을 비활성화하고 접근성 상태에도 disabled를 전달합니다. readOnly는 수량 변경과 Remove 콜백 호출을 막지만 값을 다른 상태로 바꾸지는 않습니다. loading은 지정된 action만 일시적으로 막으며, 해당 action의 indicator를 표시합니다. 따라서 removable의 최솟값에서도 Decrement가 disabled, readOnly 또는 decrement loading이면 onRemove가 호출되지 않습니다.
Lynx에는 HTML <form>, hidden <input>, FormData 제출 모델이 없으므로 웹의 inputProps와 hidden input 기반 Form 예제를 제공하지 않습니다. 수량을 제출해야 할 때는 value와 onValueChange로 앱 상태를 관리한 뒤, 제출 또는 네트워크 요청을 만드는 코드에서 그 상태를 payload에 직접 넣으세요. 이 방식은 UI 표시용 getValueText와 서버에 보낼 raw 숫자 값을 분리할 수 있습니다.
Quantity Picker의 용도를 설명하는 accessibility-label을 제공하세요. 이 label은 현재 수량을 표시하는 요소의 이름으로 사용되며, getValueText가 반환한 문자열이나 숫자는 접근성 값에도 반영됩니다.
Registry 컴포넌트는 감소, 증가, 삭제 버튼에 기본 접근성 label을 제공합니다. 문맥에 맞게 바꾸려면 decrementAccessibilityLabel, incrementAccessibilityLabel, removeAccessibilityLabel을 사용하세요. 특히 removable을 사용할 때는 삭제 대상을 알 수 있는 label을 제공해야 합니다.
disabled는 접근성 상태에도 반영됩니다. readOnly와 loading으로 동작을 막았다면 주변 label이나 안내 텍스트로 제한 상태를 설명하세요.
HTML 요소와 버튼 대신 Lynx native <view>와 접근성 요소를 렌더링하고 tap으로 동작합니다.
aria-* 대신 accessibility-*와 Registry의 접근성 label props를 사용합니다.HTML form, hidden input, FormData, inputProps를 지원하지 않습니다. 제출할 수량은 value와 onValueChange로 관리해 요청 payload에 직접 넣으세요.
브라우저의 form 검증과 키보드 focus 모델이 없습니다. required 검증과 제출은 앱에서 처리합니다.