Number Input

Number Input (숫자 입력)

숫자를 입력하고 스테퍼 버튼으로 값을 증가·감소시키는 컴포넌트예요. 최소·최대·단계·포맷 설정 등을 지원해요.

출처: 문서

본문

사용법 (Usage)

import { NumberInput } from "@chakra-ui/react"

<NumberInput.Root>
  <NumberInput.Label />
  <NumberInput.ValueText />
  <NumberInput.Control>
    <NumberInput.IncrementTrigger />
    <NumberInput.DecrementTrigger />
  </NumberInput.Control>
  <NumberInput.Scrubber />
  <NumberInput.Input />
</NumberInput.Root>

:::info

폐쇄형 컴포넌트 구성을 선호한다면 아래 스니펫을 확인해 보세요.

:::

단축키 (Shortcuts)

NumberInput 컴포넌트는 흔한 사용 사례에 대한 단축키 집합을 제공해요.

NumberInputControl

이 컴포넌트는 기본적으로 NumberInput.IncrementTrigger와 NumberInput.DecrementTrigger를 내부에 렌더링해요.

이렇게 쓰는 것은:

<NumberInput.Control />

트리거를 커스터마이즈할 필요가 없을 때 이렇게 쓰는 것의 약칭이에요:

<NumberInput.Control>
  <NumberInput.IncrementTrigger />
  <NumberInput.DecrementTrigger />
</NumberInput.Control>

예제 (Examples)

크기 (Sizes)

NumberInput.Root 컴포넌트에 size prop을 전달해 숫자 입력의 크기를 변경해요.

포맷 (Formatting)

NumberInput.Root 컴포넌트에 formatOptions prop을 전달해 숫자 입력 값을 포맷해요. 이 값은 Intl.NumberFormatOptions에 매핑되며 현재 로케일에 따라 적용돼요.

최소·최대 (Min and Max)

NumberInput.Root 컴포넌트에 min과 max prop을 전달해 숫자 입력의 최솟값과 최댓값을 설정해요.

입력된 값이 min보다 작거나 max보다 크면, blur 시점이나 Enter 키 입력 시 값이 가장 가까운 경계로 클램프돼요.

단계 (Step)

NumberInput.Root 컴포넌트에 step prop을 전달해 숫자 입력의 증가·감소 간격을 변경해요.

제어 (Controlled)

NumberInput.Root 컴포넌트에 value와 onValueChange prop을 전달해 숫자 입력 값을 제어해요.

모바일 스테퍼 (Mobile Stepper)

숫자 입력을 모바일 스테퍼로 구성하는 예시예요.

마우스 휠 (Mouse Wheel)

NumberInput.Root 컴포넌트에 allowMouseWheel prop을 전달해 마우스 휠로 값을 변경하는 것을 활성화하거나 비활성화해요.

비활성화 (Disabled)

NumberInput.Root 컴포넌트에 disabled prop을 전달해 숫자 입력을 비활성화해요.

무효 (Invalid)

Field 컴포넌트와 invalid prop을 사용해 숫자 입력이 무효임을 나타내요.

도우미 텍스트 (Helper Text)

Field와 Field.HelperText 컴포넌트를 조합해 숫자 입력에 도우미 텍스트를 추가해요.

요소 (Element)

숫자 입력을 입력 그룹 컴포넌트와 조합해 왼쪽이나 오른쪽에 요소를 추가하는 예시예요.

스크러버 (Scrubber)

NumberInput.Scrubber 컴포넌트를 사용해 숫자 입력이 스크러버 상호작용을 지원하게 해요.

Hook Form

NumberInput 컴포넌트를 react-hook-form과 함께 사용하는 예시예요.

폐쇄형 컴포넌트 (Closed Component)

숫자 입력을 폐쇄형 컴포넌트 구성으로 설정하는 방법이에요.

프로젝트에 폐쇄형 컴포넌트를 자동으로 추가하려면 다음 명령을 실행해요:

npx @chakra-ui/cli snippet add number-input

이렇게 사용해요.

<NumberInputRoot>
  <NumberInputField />
</NumberInputRoot>

가이드 (Guides)

왜 문자열 값을 사용하나요? (Why use string values?)

NumberInput 컴포넌트를 제어할 때는 숫자로 변환하지 말고 문자열 값을 사용해요. 이렇게 하면 특히 소수점·천 단위 구분자가 다른 통화(예: 1.523,30 vs 1,523.30)에서 로케일별 포맷을 보존할 수 있어요.

const [value, setValue] = useState("0")

<NumberInput.Root
  value={value}
  onValueChange={(details) => setValue(details.value)}
>
  {/* ... */}
</NumberInput.Root>

폼 제출을 위해 숫자 값이 필요하다면 NumberInput.Context를 사용해 valueAsNumber에 접근해요:

<NumberInput.Root
  value={value}
  onValueChange={(details) => setValue(details.value)}
>
  <NumberInput.Input />
  <NumberInput.Context>
    {(context) => (
      <input type="hidden" name="amount" value={context.valueAsNumber} />
    )}
  </NumberInput.Context>
</NumberInput.Root>

Props

Root

NumberInput 컴포넌트의 Root 부분에 대한 prop 테이블 (대화형 문서 참고).