InputNumber

숫자 값을 입력하고 증감 버튼으로 조절하는 입력 필드

개요

InputNumber는 숫자 전용 입력 컴포넌트입니다. 증감 버튼과 step 단위 조절, 최소/최대 범위 제한, 키보드 입력을 지원합니다.

주요 특징

• ✅ 증감 버튼: +/- Stepper 버튼으로 값 조절
• ✅ 범위 제한: min, max 값 설정 및 초과 방지
• ✅ step 조절: 정수/소수 증감 단위 설정
• ✅ 키보드 입력: 직접 숫자 입력 및 화살표 키 조절
• ✅ 숫자 전용: 문자 입력 자동 차단
• ✅ 읽기 전용/비활성화: readOnly, disabled 상태 지원
• ✅ 오류 상태: 범위 초과 시 버튼 비활성화로 시각적 피드백
• ✅ 다양한 크기: xs, sm, md, lg, xl
• ✅ 디자인 토큰: 테마 커스터마이징 지원

Sizes

<InputNumber size="xs" defaultValue={10} />
<InputNumber size="sm" defaultValue={10} />
<InputNumber size="md" defaultValue={10} />
<InputNumber size="lg" defaultValue={10} />
<InputNumber size="xl" defaultValue={10} />

사용 예시

기본 사용

<InputNumber defaultValue={0} onValueChange={(val) => console.log(val)} />
<InputNumber placeholder="숫자를 입력하세요" />

Step 값 설정

정수 또는 소수 단위로 증감할 수 있습니다.

<InputNumber defaultValue={0} step={10} />
<InputNumber defaultValue={0.5} step={0.1} min={0} max={1} />

최소/최대 범위 제한

min과 max로 입력 가능한 범위를 제한합니다. 범위를 초과하는 값은 자동으로 제한됩니다.

<InputNumber defaultValue={50} min={0} max={100} />

읽기 전용 상태

readOnly로 읽기 전용, disabled로 비활성화 상태를 설정합니다.

<InputNumber defaultValue={200} readOnly />
<InputNumber defaultValue={50} disabled />

오류 상태 표시

최소/최대 범위에 도달하면 증감 버튼이 비활성화되어 시각적으로 제한 상태를 표현합니다.

{/* min=0 도달: 감소 버튼 비활성화 */}
<InputNumber value={0} min={0} max={10} />
{/* max=10 도달: 증가 버튼 비활성화 */}
<InputNumber value={10} min={0} max={10} />

API Reference

Props

Events

기본 사용법

import { InputNumber } from "@vortex/ui-foundation"
 
<InputNumber defaultValue={10} />
<InputNumber defaultValue={50} min={0} max={100} step={5} />

접근성

권장 사항

• ✅ min/max 설정으로 유효 범위를 제한
• ✅ 키보드 접근: 증감 버튼 Tab 이동, 직접 숫자 입력, 화살표 키 증감
• ✅ 숫자만 입력 가능하도록 자동 제한
• ❌ 범위 제한 없는 무한 입력 지양

관련 컴포넌트

• Input: 일반 텍스트 입력
• Slider: 범위 내 값 조절