NumberField

양옆의 버튼으로 값을 늘리고 줄이는 숫자 컨트롤이에요. 수량, 인원, 한 페이지에 보일 개수처럼 범위가 정해진 값에 써요. 범위가 없거나 자릿수가 긴 숫자는 Input을 써요.

사용 예시

라벨과 도움말

Field로 감싸면 라벨을 눌렀을 때 NumberField에 포커스가 가요.

수량

한 번에 20개까지 주문할 수 있어요.

tsx

<Field>  <FieldLabel>수량</FieldLabel>  <NumberField value={quantity} onValueChange={setQuantity} min={1} max={20} className="w-32"               decrementLabel="수량 줄이기" incrementLabel="수량 늘리기" />  <FieldHelp>한 번에 20개까지 주문할 수 있어요.</FieldHelp></Field>

권장

min과 max를 정하면 값이 범위를 벗어나지 않아요.

지양

범위를 정하지 않으면 계속 눌러서 수량이 음수가 될 수 있어요.

배경

폼에 NumberField가 여러 개 있을 때는 bare를 써요. 하나만 있거나 NumberField가 눈에 띄어야 하면 well을 써요.

tsx

<NumberField value={quantity} onValueChange={setQuantity} min={1} max={20} className="w-32"             decrementLabel="수량 줄이기" incrementLabel="수량 늘리기" aria-label="수량" /><NumberField value={perPage} onValueChange={setPerPage} surface="well" min={10} max={100} className="w-32"             decrementLabel="개수 줄이기" incrementLabel="개수 늘리기" aria-label="페이지당 개수" />

목록 줄에서 수량 고치기

장바구니처럼 줄마다 값이 있는 곳에서 써요. 빼기와 더하기 버튼은 평소에 옅게 보여요.

무선 마우스
USB-C 케이블

tsx

<ul className="frame rounded-r12 divide-line flex flex-col divide-y">  {cart.map(item => (    <li key={item.name} className="flex items-center justify-between gap-2 py-1 pr-1 pl-4">      <span className="text-value">{item.name}</span>      <NumberField surface="ghost" size="sm" value={item.count} onValueChange={count => change(item, count)} min={1} max={20} className="w-28"                   decrementLabel="수량 줄이기" incrementLabel="수량 늘리기" aria-label={`${item.name} 수량`} />    </li>  ))}</ul>

한계값

왼쪽은 값이 min이고 오른쪽은 max예요.

tsx

<NumberField value={quantity} onValueChange={setQuantity} min={1} max={20} className="w-32"             decrementLabel="수량 줄이기" incrementLabel="수량 늘리기" aria-label="수량" />

수량

1부터 20까지 입력할 수 있어요.

권장

도움말에 범위를 적으면 버튼이 비활성인 이유를 눌러 보기 전에 알 수 있어요.

수량

지양

버튼만 비활성이면 눌리지 않는 이유를 알 수 없어요.

증감 단위

금액처럼 1이 아닌 단위로 바뀌는 값에 step을 줘요. 버튼을 누르고 있으면 값이 계속 바뀌어요.

충전 금액

tsx

<Field>  <FieldLabel>충전 금액</FieldLabel>  <NumberField value={topUp} onValueChange={setTopUp} min={1000} max={100000} step={1000} className="w-40"               decrementLabel="금액 줄이기" incrementLabel="금액 늘리기" /></Field>

버튼 옆

옆에 있는 컨트롤과 size를 맞춰요. NumberField가 lg면 버튼도 lg예요.

내보낼 가로 크기

tsx

<Field>  <FieldLabel>내보낼 가로 크기</FieldLabel>  <div className="flex gap-2">    <NumberField value={width} onValueChange={setWidth} min={1} max={4096} size="lg" className="w-32"                 decrementLabel="가로 줄이기" incrementLabel="가로 늘리기" />    <Button color="brand" emphasis="solid" size="lg">적용</Button>  </div></Field>

권장

너비를 값에 맞추면 버튼이 값 가까이에 있어요.

지양

너비를 부모에 맞춰 늘리면 버튼이 값에서 멀어져요.

설정 줄

설정 화면처럼 라벨과 컨트롤을 한 줄에 둘 때 써요. 줄이 촘촘하면 sm을 써요.

한 페이지에 보일 개수

tsx

<Field layout="split">  <FieldLabel>한 페이지에 보일 개수</FieldLabel>  <NumberField value={perPage} onValueChange={setPerPage} min={10} max={100} step={10} size="sm" className="w-28"               decrementLabel="개수 줄이기" incrementLabel="개수 늘리기" /></Field>

틀린 값

값을 비우고 포커스를 옮기면 value가 null이 돼요. 값이 꼭 필요하면 Field에 invalid를 주고 FieldError에 필요한 값을 적어요.

한 페이지에 보일 개수

10에서 100 사이의 개수를 입력하세요.

tsx

<Field invalid={perPage === null}>  <FieldLabel>한 페이지에 보일 개수</FieldLabel>  <NumberField value={perPage} onValueChange={setPerPage} min={10} max={100} step={10} className="w-32"               decrementLabel="개수 줄이기" incrementLabel="개수 늘리기" />  {perPage === null && <FieldError>10에서 100 사이의 개수를 입력하세요.</FieldError>}</Field>

비활성

값을 바꿀 수 없을 때 disabled를 줘요. 바꿀 수 없는 이유를 도움말에 함께 적어요.

수량

품절된 상품은 수량을 바꿀 수 없어요.

tsx

<Field>  <FieldLabel>수량</FieldLabel>  <NumberField value={quantity} onValueChange={setQuantity} min={1} max={20} disabled className="w-32"               decrementLabel="수량 줄이기" incrementLabel="수량 늘리기" />  <FieldHelp>품절된 상품은 수량을 바꿀 수 없어요.</FieldHelp></Field>

컨트롤

surface

size

disabled

invalid

값4

tsx

<NumberField value={count} onValueChange={setCount} min={1} max={20} decrementLabel="개수 줄이기" incrementLabel="개수 늘리기" aria-label="개수" />

명세

이름
이름	값	기본
속성
surface	bare, well, ghost	bare
bare는 투명 배경에 테두리, well은 회색 배경이에요. ghost는 평소에 글자만 보이고, 마우스를 올리면 옅은 배경, 입력하면 조금 진한 배경이 생겨요. 여러 개가 나란히 있으면 bare, 하나만 있으면 well, 표 셀이나 목록 줄에서 값을 바로 고치면 ghost를 써요.
value	number \| null	-
호출하는 쪽에서 값을 관리해요.
defaultValue	number	-
처음 값이에요.
onValueChange	(value: number \| null, eventDetails) => void	-
값이 바뀌면 호출돼요.
min	number	-
min이 0 이상이면 음수 기호를 입력할 수 없어요.
max	number	-
범위 밖의 값을 입력하면 포커스를 옮길 때 min이나 max로 바뀌어요.
step	number	1
직접 입력한 값도 포커스를 옮길 때 step 간격에 맞춰져요.
decrementLabel	string	필수
스크린 리더가 읽는 빼기 버튼의 이름이에요.
incrementLabel	string	필수
스크린 리더가 읽는 더하기 버튼의 이름이에요.
size	sm, md, lg	md
높이가 32, 36, 40px이에요.
disabled	boolean	false
양옆 버튼 2개가 모두 비활성이 돼요.
readOnly	boolean	false
버튼도 비활성이 되고 값은 폼과 함께 제출돼요.
className	string	-
그대로 넘어가는 속성
id	string	-
안에 있는 입력 요소에 붙어요.
aria-invalid	true	-
버튼을 포함한 전체에 danger 테두리가 보여요.