WIZ Design System

한눈에#

SMS·이메일 코드, 인증 앱 OTP, 계정 복구 코드를 칸 단위로 받는 입력입니다. 타이핑하면 다음 칸으로 자동 이동하고, 코드를 통째로 붙여넣으면 칸에 나눠 채워집니다. 값은 항상 갭 없는 문자열("123")이라 소비자는 onComplete로 완성 시점만 받으면 됩니다 — 검증은 소비자(서버) 몫, 이 컴포넌트는 입력만 합니다.

칸 단위 입력
자동 이동 · 붙여넣기 분배
one-time-code 자동완성
role=group

타이핑하면 다음 칸으로 — 값은 갭 없는 문자열

사용 시점#

고정 길이 코드를 칸 단위로 받을 때 씁니다. 자유 형식·가변 길이 입력에는 일반 Input을 쓰세요.

권장 — 이렇게 쓰세요

지양 — 이러지 마세요

코드 입력 — SMS·OTP·PIN을 칸 단위로 — 기본 6칸 숫자

자유 입력엔 부적합 — 가변·자유 형식엔 일반 Input — 칸 입력은 고정 길이 코드 전용

복구 코드 — 영숫자 코드는 charSet='alphanumeric' + length로

동작#

입력	결과
문자 타이핑	현재 칸을 채우고 다음 칸으로 이동
붙여넣기	커서 칸부터 여러 칸에 분배(유효 문자만)
`Backspace`	현재 칸 비우기 / 빈 칸이면 이전 칸
`←` `→`	칸 간 포커스 이동
허용 외 문자	무시(numeric=0–9, alphanumeric=영숫자)
`invalid`	각 칸 테두리 강조 + `aria-invalid`

Props#

Prop	타입	기본값	설명
`length`	`number`	`6`	칸 수 — 기본 6 (1..12로 클램프)
`value`	`string`	—	제어 값(부모가 상태 소유). 주면 defaultValue는 무시된다.
`defaultValue`	`string`	—	비제어 초기값
`onChange`	`(value: string) => void`	—	값이 바뀔 때마다 호출 — 갭 없는 전체 코드 문자열
`onComplete`	`(value: string) => void`	—	모든 칸이 채워졌을 때 호출 — 완성된 코드
`charSet`	`'numeric' \| 'alphanumeric'`	`numeric`	허용 문자 — 숫자만 / 영숫자. 기본 numeric
`disabled`	`boolean`	`false`	비활성
`invalid`	`boolean`	`false`	오류 상태(테두리 강조 + aria-invalid)
`autoFocus`	`boolean`	`false`	첫 칸 자동 포커스
`name`	`string`	—	폼 제출용 hidden input name(주면 전체 코드를 제출)
`aria-label`	`string`	`일회용 코드`	그룹 라벨 — 보조기술용

코드 검증은 소비자(서버) 몫입니다 — 어드민 계정 복구(Security Settings 패턴) 흐름에서 복구 코드 입력에 씁니다.

접근성#

계약	구현
그룹	컨테이너 `role="group"` + `aria-label`
칸 라벨	각 칸 `aria-label`(“N번째 자리”)
코드 자동완성	첫 칸 `autocomplete="one-time-code"`(SMS·이메일 코드)
숫자 키패드	numeric일 때 `inputmode="numeric"`
오류	`invalid` 시 각 칸 `aria-invalid`