OTP Input

کامپوننت OtpInput برای دریافت کد یک‌بارمصرف (OTP) استفاده می‌شود؛ مثل کد تأیید پیامکی. هر رقم در یک خانه‌ی جداگانه نمایش داده می‌شود و بعد از وارد کردن هر رقم، فوکوس به‌صورت خودکار به خانه‌ی بعدی می‌رود.

Import

import { OtpInput } from "fara-ui";

اگر هنوز FaraUI را نصب و راه‌اندازی نکرده‌ای، ابتدا صفحه‌ی شروع به کار را ببین.

Basic Usage

import { useState } from "react";
import { OtpInput } from "fara-ui";

export function VerifyCode() {
  const [otp, setOtp] = useState("");
  const [message, setMessage] = useState("");

  function verify(code) {
    setMessage(code === "12345" ? "کد صحیح است" : "کد واردشده نادرست است");
  }

  return (
    <div>
      <OtpInput length={5} value={otp} onChange={setOtp} onComplete={verify} />
      {message && <p>{message}</p>}
    </div>
  );
}

value همیشه باید یک رشته باشد. وقتی کاربر هنوز همه‌ی رقم‌ها را وارد نکرده، رشته کوتاه‌تر از length است؛ برای مثال مقدار یک کد پنج‌رقمی می‌تواند "12" باشد.

Playground

length

error

disabled

<OtpInput length={5} value={otp} onChange={setOtp} />

Behavior

• فوکوس خودکار: بعد از وارد کردن هر رقم، فوکوس به خانه‌ی بعدی می‌رود؛ با Backspace روی خانه‌ی خالی، به خانه‌ی قبلی برمی‌گردد.
• Paste: کاربر می‌تواند کل کد را یک‌جا paste کند؛ ارقام به‌صورت خودکار در خانه‌ها پخش می‌شوند.
• فقط عدد: ورودی غیررقمی به‌صورت خودکار حذف می‌شود (inputMode="numeric").
• onComplete: وقتی همه‌ی خانه‌ها پر شوند صدا زده می‌شود — بهترین جا برای ارسال کد به سرور بدون نیاز به دکمه‌ی تأیید.

Error State

با فعال‌کردن error حاشیه‌ی خانه‌ها قرمز می‌شود؛ برای وقتی که کد وارد‌شده اشتباه بوده است.

<OtpInput length={6} value={otp} error={isInvalid} onChange={setOtp} />

پس از درخواست دوباره‌ی کد، state را پاک کن:

<button type="button" onClick={() => setOtp("")}>
  ورود دوباره‌ی کد
</button>

Data Attributes and Customize CSS

OtpInput hookهای زیر را تولید می‌کند:

<div data-fara-otp-input>
  <input data-fara-otp-input-slot data-filled="true" />
  <input data-fara-otp-input-slot data-error="true" />
</div>

Attribute	کاربرد
data-fara-otp-input	ریشه‌ی کامپوننت
data-fara-otp-input-slot	هر خانه‌ی یک‌رقمی
data-filled	پر بودن خانه
data-error	حالت خطا

className روی wrapper اصلی اعمال می‌شود:

<OtpInput className="login-otp" length={6} value={otp} onChange={setOtp} />

.login-otp {
  gap: 12px;
}

[data-fara-otp-input-slot][data-filled] {
  border-color: #7c3aed;
}

[data-fara-otp-input-slot][data-error] {
  border-color: #dc2626;
}

چیدمان داخلی OtpInput عمداً ltr است تا رقم اول همیشه در سمت درست قرار بگیرد؛ این رفتار را در صفحه‌ی RTL تغییر نده.

Accessibility

• هر خانه یک aria-label توصیفی مثل «رقم ۲ از ۵» دارد.
• خانه‌ها با inputMode="numeric" روی موبایل صفحه‌کلید عددی باز می‌کنند.

Props

Prop	Type	Default	Description
value	string	-	مقدار فعلی (الزامی، controlled)
onChange	(value: string) => void	-	هنگام تغییر هر رقم صدا زده می‌شود (الزامی)
length	number	4	تعداد خانه‌ها
onComplete	(value: string) => void	-	وقتی همه‌ی خانه‌ها پر شوند صدا زده می‌شود
disabled	boolean	false	غیرفعال کردن ورودی
error	boolean	false	نمایش حالت خطا (حاشیه‌ی قرمز)
className	string	-	کلاس CSS اضافی برای سفارشی‌سازی