InputOTP

인증 코드, PIN 등 고정 길이 코드를 입력받는 OTP 입력 컴포넌트

개요

InputOTP 컴포넌트는 input-otp 라이브러리를 기반으로, 하나의 입력을 여러 개의 슬롯으로 나누어 표시하는 OTP(One-Time Password) 입력 컴포넌트입니다. 붙여넣기, 가짜 커서(caret) 애니메이션, 패턴 검증을 지원합니다.

주요 특징

• ✅ 슬롯 기반 입력: 문자마다 개별 슬롯에 표시, 활성 슬롯 하이라이트
• ✅ 그룹 분리: InputOTPSeparator로 코드를 시각적으로 구간 분리
• ✅ 크기 옵션: xs, sm, md, lg, xl 5가지 사이즈
• ✅ 패턴 검증: pattern으로 숫자만 입력 등 제한 가능
• ✅ 붙여넣기 지원: 코드 전체 붙여넣기 시 슬롯에 자동 분배
• ✅ 접근성: 단일 input 기반으로 스크린 리더 친화적

사용 예시

기본 (6자리 코드)

<InputOTP maxLength={6}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>

그룹 분리 (구분자 포함)

InputOTPSeparator로 3자리씩 나누어 표시합니다.

<InputOTP maxLength={6}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
  </InputOTPGroup>
  <InputOTPSeparator />
  <InputOTPGroup>
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>

숫자만 입력

pattern과 inputMode로 숫자 입력만 허용합니다.

<InputOTP maxLength={6} pattern="^[0-9]+$" inputMode="numeric">
  {/* ... */}
</InputOTP>

제어 모드

import { useState } from "react"
import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from "@vortex/ui-foundation"
 
function OtpForm() {
  const [value, setValue] = useState("")
 
  return (
    <InputOTP
      maxLength={6}
      value={value}
      onChange={setValue}
      onComplete={(code) => console.log("입력 완료:", code)}
    >
      <InputOTPGroup>
        <InputOTPSlot index={0} />
        <InputOTPSlot index={1} />
        <InputOTPSlot index={2} />
        <InputOTPSlot index={3} />
        <InputOTPSlot index={4} />
        <InputOTPSlot index={5} />
      </InputOTPGroup>
    </InputOTP>
  )
}

Sizes

size prop으로 슬롯 크기와 폰트 크기를 조정합니다. InputOTP, InputOTPGroup, InputOTPSlot에 동일한 size를 지정하세요.

<InputOTP maxLength={4} size="sm">
  <InputOTPGroup size="sm">
    <InputOTPSlot index={0} size="sm" />
    {/* ... */}
  </InputOTPGroup>
</InputOTP>
 
<InputOTP maxLength={4}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    {/* ... */}
  </InputOTPGroup>
</InputOTP>
 
<InputOTP maxLength={4} size="lg">
  <InputOTPGroup size="lg">
    <InputOTPSlot index={0} size="lg" />
    {/* ... */}
  </InputOTPGroup>
</InputOTP>

API Reference

InputOTP Props

input-otp 라이브러리 OTPInput의 props를 상속합니다.

InputOTPGroup Props

InputOTPSlot Props

InputOTPSeparator Props

div 요소의 props를 전달합니다. role="separator"와 함께 마이너스(-) 아이콘이 기본 표시됩니다.

기본 사용법

import {
  InputOTP,
  InputOTPGroup,
  InputOTPSlot,
} from "@vortex/ui-foundation"
 
;<InputOTP maxLength={6}>
  <InputOTPGroup>
    <InputOTPSlot index={0} />
    <InputOTPSlot index={1} />
    <InputOTPSlot index={2} />
    <InputOTPSlot index={3} />
    <InputOTPSlot index={4} />
    <InputOTPSlot index={5} />
  </InputOTPGroup>
</InputOTP>

접근성

• 내부적으로 단일 <input> 요소를 사용하므로 스크린 리더가 하나의 입력 필드로 인식합니다.
• 활성 슬롯에는 가짜 커서(caret) 애니메이션이 표시되어 입력 위치를 시각적으로 안내합니다.
• ✅ FormItem의 label과 함께 사용하여 입력 목적을 명확히 하세요.
• ✅ autoComplete="one-time-code"를 지정하면 모바일에서 SMS 인증 코드 자동 입력이 가능합니다.

관련 컴포넌트

• Input: 일반 텍스트 입력 필드
• FormItem: OTP 입력에 라벨과 에러 메시지 연결