Skip to Content

InputNumber

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


개요

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

주요 특징

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

Sizes


사용 예시

기본 사용

Step 값 설정

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

최소/최대 범위 제한

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

버튼 숨김

hideButtons로 +/- 증감 버튼을 숨길 수 있습니다. 키보드 화살표 키로 값을 변경할 수 있습니다.

정수 모드

integerOnly로 소수점 입력을 차단합니다. 소수점(.) 키 입력이 차단되고, 값은 자동으로 정수로 변환됩니다.

텍스트 정렬

textAlign으로 입력 필드 내 텍스트 정렬을 설정합니다. 기본값은 "center"입니다.

읽기 전용 상태

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

오류 상태 표시

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


API Reference

Props

PropTypeDefaultDescription
valuenumber (allowEmpty면 number | null)-값 (제어 컴포넌트)
defaultValuenumber-초기 기본값
stepnumber1증감 단위
minnumber-Infinity최소 값
maxnumberInfinity최대 값
disabledbooleanfalse비활성화 여부
readOnlybooleanfalse읽기 전용 여부
size"xs" | "sm" | "md" | "lg" | "xl""md"컴포넌트 크기
placeholderstring-플레이스홀더 텍스트
hideButtonsbooleanfalse+/- 버튼 숨김 여부
integerOnlybooleanfalse정수만 입력 (소수점 차단)
textAlign"left" | "center" | "right""center"텍스트 정렬
classNamestring-추가 CSS 클래스 (루트)
classNames{ input?: string; group?: string }-부품별 클래스. input은 입력 칸, group은 입력 상자(NumberField.Group, 테두리·−·+ 포함)에 기존 클래스 뒤로 붙음. 주지 않으면 지금과 같음
styles{ input?: React.CSSProperties; group?: React.CSSProperties }-부품별 인라인 스타일. input은 입력 칸, group은 입력 상자. 주지 않으면 지금과 같음
aria-invalidboolean-오류 상태. 입력란 aria-invalid
allowEmptybooleanfalse빈 값 허용. 켜면 비울 때 onValueChange(null), value·콜백 인자가 number | null
formatIntl.NumberFormatOptionsbase-ui 기본표시 서식 (base-ui format)
snapOnStepbooleanfalse증감할 때 step 배수로 맞춤 (직접 입력은 맞추지 않음). 켜면 무한 min·max를 base-ui에 넘기지 않음
finiteBoundsbooleanfalsemin·max가 없거나 ±Infinity면 base-ui에 넘기지 않음. Home·End가 정해진 경계가 있을 때만 그 값으로 감
idstring자동입력란 id
namestring"InputNumber"폼 제출 이름
requiredbooleanfalseHTML required (브라우저 제출 검증)
ariaLabelstring-입력란 aria-label
ariaLabelledBystring-입력란 aria-labelledby
ariaDescribedBystring-입력란 aria-describedby
ariaRequiredboolean-입력란 aria-required
titlestring-입력란 native tooltip
inputMode"numeric" | "decimal" | …-입력란 inputmode (모바일 키보드)

입력란 속성은 하이픈 없는 이름으로 받아 선언한 것만 넘깁니다(aria-invalid만 예전 이름). 그 밖의 props는 버립니다.

Events

EventTypeDescription
onValueChange(value: number) => void (allowEmpty면 (value: number | null) => void)값 변경 시 호출. allowEmpty가 꺼져 있으면 비워도 불리지 않음
onFocusFocusEventHandler<HTMLInputElement>입력란 포커스
onBlurFocusEventHandler<HTMLInputElement>입력란 포커스 해제
onKeyDownKeyboardEventHandler<HTMLInputElement>입력란 키 입력. integerOnly 키 처리 뒤에 불림

기본 사용법

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

접근성

권장 사항

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

관련 컴포넌트

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