# Persian Number Input — React Component for Farsi, Arabic & RTL Number Formatting
[فارسی](./README.fa.md) | English
A lightweight React library for **Persian (Farsi) and Arabic number inputs** with automatic digit conversion, thousand-separator formatting, decimal precision, and full RTL support. No more manual conversion — users type in their native digits, your form receives clean English numbers.
[](https://www.npmjs.com/package/persian-number-input)
[](https://www.npmjs.com/package/persian-number-input)
[](https://bundlephobia.com/package/persian-number-input)
[](https://github.com/javadSharifi/persian-number-input/blob/main/LICENSE)
## 🚀 [Live Demo](https://persian-number-input.netlify.app/)
---
## Why Persian Number Input?
Building forms for Persian or Arabic-speaking users comes with real challenges:
- Users naturally type `۱۲۳۴` — but your API expects `1234`
- Standard `` doesn't support Persian or Arabic digits at all
- Cursor jumps erratically when formatting thousand separators on the fly
- Decimal handling differs across locales (`٫` vs `.`)
- RTL inputs need right-aligned text and correct suffix placement
This library solves all of these automatically:
```
User types: ۱۲۳۴۵۶۷
Displayed as: ۱,۲۳۴,۵۶۷
Form receives: "1234567"
```
---
## ✨ Features
- 🔢 **Automatic digit conversion** — Persian (۰-۹) and Arabic (٠-٩) to English and back
- 🌍 **Multi-locale** — `fa` (Farsi/Persian), `ar` (Arabic), `en` (English)
- 📊 **Thousand separator formatting** — customizable separator character and group size
- 💰 **Currency-ready** — add suffix (e.g. تومان, ریال, ر.س) as a visual-only overlay, and custom decimal separator
- ⚡ **~1KB gzipped** — zero extra dependencies, pure TypeScript
- 🎯 **TypeScript** — full type definitions included
- 🔄 **Cursor-position preservation** — no jump on re-format
- 📋 **Smart paste handling** — pasted content is sanitized and auto-converted
- ✅ **Min/max validation** — soft enforcement with `aria-invalid` and automatic clamp on blur
- ♿ **Accessible** — follows WCAG input best practices
---
## 📦 Installation
```bash
npm install persian-number-input
# or
yarn add persian-number-input
# or
pnpm add persian-number-input
```
> **Requirements:** React 16.8+, works with Next.js, Vite, CRA, and any React-based framework.
---
## 🎯 Quick Start
```tsx
import { PersianNumberInput } from "persian-number-input";
function App() {
return (
console.log(value)} // "1234567"
/>
);
}
```
Output displayed to user: `۱,۲۳۴,۵۶۷`
---
## 📚 Usage Examples
### Persian Toman currency input
```tsx
console.log(value)}
/>
```
Displayed to user: `۵,۰۰۰,۰۰۰` with `تومان` rendered as a visual-only overlay next to the input.
The suffix is rendered outside the input's value — it never interferes with cursor position, selection, or backspace behavior.
---
### Arabic locale (SAR)
```tsx
console.log(value)}
/>
```
Displayed to user: `٩٨٧,٦٥٤` with `ر.س` rendered as a visual-only overlay.
---
### Decimal numbers with custom separator
```tsx
console.log(value)}
/>
```
Displayed: `۱,۲۳۴٫۵۶`
---
### Price input with min/max validation
```tsx
console.log(value)}
/>
```
Displayed to user: `۰` with `ریال` rendered as visual-only overlay.
---
### With React Hook Form
```tsx
import { useForm, Controller } from "react-hook-form";
import { PersianNumberInput } from "persian-number-input";
function ProductForm() {
const { control, handleSubmit } = useForm();
return (
);
}
```
---
### Using the hook directly (advanced)
```tsx
import { usePersianNumberInput } from "persian-number-input";
function CustomInput() {
const { value, onChange, onBlur, rawValue, isInvalid } =
usePersianNumberInput({
initialValue: 1000,
locale: "fa",
suffix: "تومان",
maxDecimals: 2,
min: 0,
max: 1000000,
onValueChange: (val) => console.log("English value:", val),
});
return (