InputNumber
숫자 값을 입력하고 증감 버튼으로 조절하는 입력 필드
개요
InputNumber는 숫자 전용 입력 컴포넌트입니다. 증감 버튼과 step 단위 조절, 최소/최대 범위 제한, 키보드 입력을 지원합니다.
주요 특징
- ✅ 증감 버튼: +/- Stepper 버튼으로 값 조절
- ✅ 범위 제한: min, max 값 설정 및 초과 방지
- ✅ step 조절: 정수/소수 증감 단위 설정
- ✅ 키보드 입력: 직접 숫자 입력 및 화살표 키 조절
- ✅ 숫자 전용: 문자 입력 자동 차단
- ✅ 버튼 숨김: hideButtons로 +/- 버튼 숨김
- ✅ 정수 모드: integerOnly로 소수점 입력 차단
- ✅ 텍스트 정렬: textAlign으로 좌측/가운데/우측 정렬
- ✅ 읽기 전용/비활성화: readOnly, disabled 상태 지원
- ✅ 오류 상태: 범위 초과 시 버튼 비활성화로 시각적 피드백
- ✅ 다양한 크기: xs, sm, md, lg, xl
- ✅ 디자인 토큰: 테마 커스터마이징 지원
Sizes
Preview
사용 예시
기본 사용
Preview
Step 값 설정
정수 또는 소수 단위로 증감할 수 있습니다.
Preview
최소/최대 범위 제한
min과 max로 입력 가능한 범위를 제한합니다. 범위를 초과하는 값은 자동으로 제한됩니다.
Preview
버튼 숨김
hideButtons로 +/- 증감 버튼을 숨길 수 있습니다. 키보드 화살표 키로 값을 변경할 수 있습니다.
Preview
정수 모드
integerOnly로 소수점 입력을 차단합니다. 소수점(.) 키 입력이 차단되고, 값은 자동으로 정수로 변환됩니다.
Preview
텍스트 정렬
textAlign으로 입력 필드 내 텍스트 정렬을 설정합니다. 기본값은 "center"입니다.
Preview
읽기 전용 상태
readOnly로 읽기 전용, disabled로 비활성화 상태를 설정합니다.
Preview
오류 상태 표시
최소/최대 범위에 도달하면 증감 버튼이 비활성화되어 시각적으로 제한 상태를 표현합니다.
Preview
API Reference
Props
| Prop | Type | Default | Description |
|---|---|---|---|
value | number (allowEmpty면 number | null) | - | 값 (제어 컴포넌트) |
defaultValue | number | - | 초기 기본값 |
step | number | 1 | 증감 단위 |
min | number | -Infinity | 최소 값 |
max | number | Infinity | 최대 값 |
disabled | boolean | false | 비활성화 여부 |
readOnly | boolean | false | 읽기 전용 여부 |
size | "xs" | "sm" | "md" | "lg" | "xl" | "md" | 컴포넌트 크기 |
placeholder | string | - | 플레이스홀더 텍스트 |
hideButtons | boolean | false | +/- 버튼 숨김 여부 |
integerOnly | boolean | false | 정수만 입력 (소수점 차단) |
textAlign | "left" | "center" | "right" | "center" | 텍스트 정렬 |
className | string | - | 추가 CSS 클래스 (루트) |
classNames | { input?: string; group?: string } | - | 부품별 클래스. input은 입력 칸, group은 입력 상자(NumberField.Group, 테두리·−·+ 포함)에 기존 클래스 뒤로 붙음. 주지 않으면 지금과 같음 |
styles | { input?: React.CSSProperties; group?: React.CSSProperties } | - | 부품별 인라인 스타일. input은 입력 칸, group은 입력 상자. 주지 않으면 지금과 같음 |
aria-invalid | boolean | - | 오류 상태. 입력란 aria-invalid |
allowEmpty | boolean | false | 빈 값 허용. 켜면 비울 때 onValueChange(null), value·콜백 인자가 number | null |
format | Intl.NumberFormatOptions | base-ui 기본 | 표시 서식 (base-ui format) |
snapOnStep | boolean | false | 증감할 때 step 배수로 맞춤 (직접 입력은 맞추지 않음). 켜면 무한 min·max를 base-ui에 넘기지 않음 |
finiteBounds | boolean | false | min·max가 없거나 ±Infinity면 base-ui에 넘기지 않음. Home·End가 정해진 경계가 있을 때만 그 값으로 감 |
id | string | 자동 | 입력란 id |
name | string | "InputNumber" | 폼 제출 이름 |
required | boolean | false | HTML required (브라우저 제출 검증) |
ariaLabel | string | - | 입력란 aria-label |
ariaLabelledBy | string | - | 입력란 aria-labelledby |
ariaDescribedBy | string | - | 입력란 aria-describedby |
ariaRequired | boolean | - | 입력란 aria-required |
title | string | - | 입력란 native tooltip |
inputMode | "numeric" | "decimal" | … | - | 입력란 inputmode (모바일 키보드) |
입력란 속성은 하이픈 없는 이름으로 받아 선언한 것만 넘깁니다(aria-invalid만 예전 이름). 그 밖의 props는 버립니다.
Events
| Event | Type | Description |
|---|---|---|
onValueChange | (value: number) => void (allowEmpty면 (value: number | null) => void) | 값 변경 시 호출. allowEmpty가 꺼져 있으면 비워도 불리지 않음 |
onFocus | FocusEventHandler<HTMLInputElement> | 입력란 포커스 |
onBlur | FocusEventHandler<HTMLInputElement> | 입력란 포커스 해제 |
onKeyDown | KeyboardEventHandler<HTMLInputElement> | 입력란 키 입력. integerOnly 키 처리 뒤에 불림 |
기본 사용법
import { InputNumber } from "@vortex/ui-foundation"
<InputNumber defaultValue={10} />
<InputNumber defaultValue={50} min={0} max={100} step={5} />접근성
권장 사항
- ✅
min/max설정으로 유효 범위를 제한 - ✅ 키보드 접근: 증감 버튼 Tab 이동, 직접 숫자 입력, 화살표 키 증감
- ✅ 숫자만 입력 가능하도록 자동 제한
- ❌ 범위 제한 없는 무한 입력 지양
관련 컴포넌트
Last updated on