React OTP Input

یک کامپوننت OTP حرفه‌ای، سبک، قابل سفارشی‌سازی و سازگار با SSR برای React.
این کامپوننت از دو حالت single و multiple پشتیبانی می‌کند و امکاناتی مثل امنیت، دسترسی‌پذیری، RTL، کنترل کامل رفتار ورودی و UX هوشمند را ارائه می‌دهد.

✨ ویژگی‌ها

• پشتیبانی از دو حالت ورودی:
  • single → یک ورودی با اسلات‌های مجازی
  • multiple → چند ورودی مستقل
• پشتیبانی از انواع ورودی:
  • numeric، alphanumeric، text
• پشتیبانی از الگوی سفارشی (pattern)
• حالت امنیتی (secure) برای نمایش نقطه به‌جای کاراکتر
• مدیریت کامل Paste، Backspace و Navigation
• پشتیبانی از RTL و LTR
• پشتیبانی از Placeholder، Separator و AutoFocus
• رویدادهای onChange و onComplete
• دسترسی‌پذیری کامل (A11y)
• سازگار با SSR و Next.js
• سبک، بدون وابستگی‌های غیرضروری

📦 نصب

npm install your-otp-input
# یا
yarn add your-otp-input
🚀 استفاده سریع
حالت Multiple (پیش‌فرض)
tsx
import { OtpInput } from "your-otp-input";

export default function Example() {
  return (
    <OtpInput
      length={6}
      onComplete={(code) => console.log("OTP:", code)}
    />
  );
}
حالت Single
tsx
<OtpInput
  mode="single"
  length={6}
  placeholder="-"
  secure
/>
⚙️ Props
نام	نوع	پیش‌فرض	توضیح
length	number	4	تعداد کاراکترهای OTP
onChange	(value: string) => void	—	هنگام تغییر مقدار
onComplete	(value: string) => void	—	وقتی مقدار کامل شد
className	string	—	کلاس سفارشی
style	CSSProperties	—	استایل inline
dir	`'ltr' \	'rtl'`	'ltr'	جهت ورودی
disabled	boolean	false	غیرفعال کردن ورودی
autoFocus	boolean	false	فوکوس خودکار
separator	ReactNode	—	جداکننده بین سلول‌ها
placeholder	string	—	placeholder هر سلول
mode	`'single' \	'multiple'`	'multiple'	حالت ورودی
inputType	`'numeric' \	'alphanumeric' \	'text'`	'numeric'	نوع ورودی
pattern	RegExp	—	الگوی سفارشی
secure	boolean	false	نمایش نقطه به‌جای کاراکتر
isError	boolean	false	حالت خطا (انیمیشن shake)
ariaLabel	string	"Verification Code"	لیبل دسترسی‌پذیری
renderInputAriaLabel	(index, total) => string	—	لیبل سفارشی برای هر سلول
🎨 استایل‌دهی
این کامپوننت کلاس‌های پایه زیر را ارائه می‌دهد:

کلاس	توضیح
otp-container	کانتینر اصلی
otp-input-base	استایل پایه ورودی
otp-field	ورودی‌های حالت multiple
otp-slot	اسلات‌های حالت single
otp-hidden-input	ورودی مخفی حالت single
otp-error	حالت خطا
otp-shake	انیمیشن خطا
otp-caret	نشانگر فعال
می‌توانید به‌راحتی override کنید:

css
.otp-field {
  border: 1px solid #ccc;
  border-radius: 8px;
}
♿ دسترسی‌پذیری (A11y)
استفاده از aria-label برای ورودی‌ها

استفاده از aria-live برای اعلام تکمیل OTP

پشتیبانی از aria-invalid در حالت خطا

پشتیبانی از screen reader برای هر سلول

🧪 رویدادها
onChange(value: string)
هنگام تغییر مقدار OTP

onComplete(value: string)
وقتی مقدار کامل شد (مثلاً ۶ رقم)

📄 لایسنس
MIT

🇬🇧 English README
(Professional, clean, npm‑ready)

md
# React OTP Input

A lightweight, accessible, customizable OTP (One-Time Password) input component for React.  
Supports both **single-input** and **multi-input** modes with full control over validation, UX behavior, accessibility, and styling.

---

## ✨ Features

- Two input modes:
  - `single` → one hidden input with visual slots
  - `multiple` → separate input fields
- Input types: `numeric`, `alphanumeric`, `text`
- Custom validation via RegExp (`pattern`)
- Secure mode (mask characters with •)
- Smart handling of paste, backspace, and navigation
- RTL & LTR support
- Custom placeholders and separators
- `onChange` and `onComplete` callbacks
- Full accessibility (A11y) support
- SSR-friendly (Next.js compatible)
- Zero unnecessary dependencies

---

## 📦 Installation

```bash
npm install your-otp-input
# or
yarn add your-otp-input
🚀 Quick Usage
Multiple Mode (default)
tsx
import { OtpInput } from "your-otp-input";

export default function Example() {
  return (
    <OtpInput
      length={6}
      onComplete={(code) => console.log("OTP:", code)}
    />
  );
}
Single Mode
tsx
<OtpInput
  mode="single"
  length={6}
  placeholder="-"
  secure
/>
⚙️ Props
Prop	Type	Default	Description
length	number	4	Number of OTP digits
onChange	(value: string) => void	—	Triggered on value change
onComplete	(value: string) => void	—	Triggered when OTP is fully filled
className	string	—	Custom class
style	CSSProperties	—	Inline styles
dir	`'ltr' \	'rtl'`	'ltr'	Input direction
disabled	boolean	false	Disable input
autoFocus	boolean	false	Auto-focus first field
separator	ReactNode	—	Separator between fields
placeholder	string	—	Placeholder for each cell
mode	`'single' \	'multiple'`	'multiple'	Input mode
inputType	`'numeric' \	'alphanumeric' \	'text'`	'numeric'	Input type
pattern	RegExp	—	Custom validation pattern
secure	boolean	false	Mask characters
isError	boolean	false	Error state (shake animation)
ariaLabel	string	"Verification Code"	A11y label
renderInputAriaLabel	(index, total) => string	—	Custom per-cell aria-label
🎨 Styling
Base CSS classes:

Class	Description
otp-container	Main wrapper
otp-input-base	Base input style
otp-field	Input fields (multiple mode)
otp-slot	Visual slots (single mode)
otp-hidden-input	Hidden input (single mode)
otp-error	Error state
otp-shake	Shake animation
otp-caret	Active caret indicator
Example override:

css
.otp-field {
  border: 1px solid #ddd;
  border-radius: 6px;
}
♿ Accessibility (A11y)
aria-label for each input

aria-live announcements for completion

aria-invalid for error states

Screen reader–friendly structure

🧪 Events
onChange(value: string)
Fired whenever the OTP value changes.

onComplete(value: string)
Fired when the OTP reaches full length.

📄 License
MIT