Persian Number Input

فارسی | English A lightweight, powerful React library for handling Persian (Farsi) and Arabic number inputs with automatic digit conversion, formatting, and localization support.

🚀 Live Demo

Experience the component in action with our interactive demo!

📊 Bundle Size

This library is extremely lightweight:

persian-number-input: ~1KB (minified + gzipped)

✨ Features

• 🔢 Automatic Digit Conversion - Seamlessly converts Persian (۰-۹) and Arabic (٠-٩) digits to English and vice versa
• 🌍 Multi-locale Support - Built-in support for Persian (fa), Arabic (ar), and English (en)
• 📊 Number Formatting - Automatic thousand separators with customizable characters
• 💰 Currency Ready - Add prefixes, suffixes, and custom decimal separators
• ⚡ Lightweight - Tiny bundle size with zero dependencies (except decimal.js for precision)
• 🎯 Type-Safe - Full TypeScript support with complete type definitions
• ♿ Accessible - Follows best practices for input accessibility
• 🎨 Customizable - Extensive configuration options for any use case
• 🔄 Real-time Formatting - Format numbers as users type with cursor position preservation
• ✅ Validation - Built-in min/max value validation and decimal precision control

📦 Installation

npm install persian-number-input

yarn add persian-number-input

pnpm add persian-number-input

🎯 Quick Start

Basic Usage

import { PersianNumberInput } from "persian-number-input";

function App() {
  return (
    <PersianNumberInput
      initialValue={1234567}
      locale="fa"
      onValueChange={(value) => console.log(value)}
    />
  );
}

Output: ۱,۲۳۴,۵۶۷

📚 Usage Examples

Currency Input (Persian Toman)

<PersianNumberInput
  initialValue={5000000}
  locale="fa"
  suffix="تومان"
  separatorCount={3}
  separatorChar=","
  onValueChange={(value) => console.log(value)}
/>

Output: ۵,۰۰۰,۰۰۰ تومان

Decimal Numbers with Custom Separator

<PersianNumberInput
  initialValue={1234.56}
  locale="fa"
  maxDecimals={2}
  decimalChar="٫"
  separatorChar=","
  onValueChange={(value) => console.log(value)}
/>

Output: ۱,۲۳۴٫۵۶

Price Input with Validation

<PersianNumberInput
  initialValue={0}
  locale="fa"
  min={0}
  max={999999999}
  suffix="ریال"
  showZero={true}
  onValueChange={(value) => console.log(value)}
/>

Output: ۰ ریال

Arabic Locale

<PersianNumberInput
  initialValue={987654}
  locale="ar"
  separatorChar=","
  suffix="ر.س"
  onValueChange={(value) => console.log(value)}
/>

Output: ٩٨٧,٦٥٤ ر.س

Using the Hook (Advanced)

import { usePersianNumberInput } from "persian-number-input";

function CustomInput() {
  const { value, onChange, onBlur, rawValue } = usePersianNumberInput({
    initialValue: 1000,
    locale: "fa",
    separatorCount: 3,
    maxDecimals: 2,
    min: 0,
    max: 1000000,
    onValueChange: (val) => {
      console.log("Raw value:", val); // "1000"
      console.log("Displayed value:", value); // "۱,۰۰۰"
    },
  });

  return (
    <input
      type="text"
      value={value}
      onChange={onChange}
      onBlur={onBlur}
      className="custom-input"
    />
  );
}

🛠️ API Reference

PersianNumberInput Props

| Prop | Type | Default | Description | | ---------------- | -------------------------------------- | ----------- | -------------------------------------------------------- | | initialValue | number \| string | undefined | Initial value of the input | | locale | "fa" \| "ar" \| "en" | "fa" | Locale for digit conversion | | separatorCount | number | 3 | Number of digits between separators | | separatorChar | string | "," | Character used for thousand separator | | decimalChar | string | Auto | Decimal separator character | | suffix | string | undefined | Suffix text (e.g., currency symbol) | | maxDecimals | number | undefined | Maximum decimal places allowed | | min | number | undefined | Minimum allowed value | | max | number | undefined | Maximum allowed value | | showZero | boolean | false | Show zero when value is empty | | onValueChange | (value: string \| undefined) => void | undefined | Callback when value changes (returns raw English digits) |

All standard HTML input props are also supported.

Utility Functions

transformNumber(rawValue, options)

Formats a number string according to locale and options.

import { transformNumber } from "persian-number-input";

const formatted = transformNumber("1234567.89", {
  locale: "fa",
  separatorCount: 3,
  separatorChar: ",",
  maxDecimals: 2,
  suffix: "تومان",
});

console.log(formatted); // "۱,۲۳۴,۵۶۷٫۸۹ تومان"

toEnglishDigits(str, decimalChar?)

Converts Persian/Arabic digits to English digits.

import { toEnglishDigits } from "persian-number-input";

console.log(toEnglishDigits("۱۲۳۴")); // "1234"
console.log(toEnglishDigits("٩٨٧٦")); // "9876"

toLocalizedDigits(numStr, locale)

Converts English digits to localized digits.

import { toLocalizedDigits } from "persian-number-input";

console.log(toLocalizedDigits("1234", "fa")); // "۱۲۳۴"
console.log(toLocalizedDigits("5678", "ar")); // "٥٦٧٨"

sanitizeNumericInput(value, maxDecimals?, decimalChar?)

Cleans and validates numeric input.

import { sanitizeNumericInput } from "persian-number-input";

console.log(sanitizeNumericInput("۱۲۳abc۴۵۶", 2)); // "123456"
console.log(sanitizeNumericInput("12.345.67", 2)); // "12.34"

🎨 Styling

The component accepts all standard input props, including className and style:

<PersianNumberInput
  initialValue={1000}
  locale="fa"
  className="custom-input"
  style={{
    padding: "12px",
    fontSize: "16px",
    border: "2px solid #4F46E5",
    borderRadius: "8px",
    textAlign: "right",
  }}
/>

With Tailwind CSS

<PersianNumberInput
  initialValue={1000}
  locale="fa"
  className="w-full px-4 py-3 text-lg border-2 border-indigo-500 rounded-lg focus:outline-none focus:ring-2 focus:ring-indigo-600 text-right"
/>

🌟 Advanced Examples

Financial Calculator

import { useState } from "react";
import { PersianNumberInput } from "persian-number-input";

function LoanCalculator() {
  const [principal, setPrincipal] = useState<string>();
  const [rate, setRate] = useState<string>();
  const [years, setYears] = useState<string>();

  const calculateMonthlyPayment = () => {
    if (!principal || !rate || !years) return 0;
    const p = parseFloat(principal);
    const r = parseFloat(rate) / 100 / 12;
    const n = parseFloat(years) * 12;
    return (p * r * Math.pow(1 + r, n)) / (Math.pow(1 + r, n) - 1);
  };

  return (
    <div className="space-y-4">
      <div>
        <label>مبلغ وام:</label>
        <PersianNumberInput
          locale="fa"
          suffix="تومان"
          onValueChange={setPrincipal}
          min={0}
        />
      </div>
      <div>
        <label>نرخ سود (٪):</label>
        <PersianNumberInput
          locale="fa"
          maxDecimals={2}
          onValueChange={setRate}
          min={0}
          max={100}
        />
      </div>
      <div>
        <label>مدت زمان (سال):</label>
        <PersianNumberInput
          locale="fa"
          onValueChange={setYears}
          min={1}
          max={30}
        />
      </div>
      <p>
        پرداخت ماهیانه: {calculateMonthlyPayment().toLocaleString("fa-IR")}{" "}
        تومان
      </p>
    </div>
  );
}

Form Integration

import { useForm, Controller } from "react-hook-form";
import { PersianNumberInput } from "persian-number-input";

function ProductForm() {
  const { control, handleSubmit } = useForm();

  const onSubmit = (data) => {
    console.log(data);
  };

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <Controller
        name="price"
        control={control}
        rules={{ required: true }}
        render={({ field }) => (
          <PersianNumberInput
            locale="fa"
            suffix="تومان"
            onValueChange={field.onChange}
            initialValue={field.value}
          />
        )}
      />
      <button type="submit">ثبت</button>
    </form>
  );
}

🔍 Why Persian Number Input?

The Problem

Working with Persian and Arabic numerals in web applications is challenging:

• Users type in their native digits, but forms expect English digits
• Number formatting varies across locales
• Maintaining cursor position during formatting is complex
• Decimal precision handling requires careful implementation

The Solution

Persian Number Input handles all these complexities automatically:

// User types: ۱۲۳۴۵۶۷
// Component displays: ۱,۲۳۴,۵۶۷
// Form receives: "1234567"

🏆 Comparison

| Feature | Persian Number Input | Native Input | Other Libraries | | --------------------- | -------------------- | ------------ | --------------- | | Auto digit conversion | ✅ | ❌ | ⚠️ Partial | | Cursor preservation | ✅ | ❌ | ⚠️ Buggy | | TypeScript support | ✅ | ✅ | ⚠️ Varies | | Multi-locale | ✅ | ❌ | ❌ | | Bundle size | 🟢 Small | 🟢 N/A | 🔴 Large | | Decimal precision | ✅ | ❌ | ⚠️ Limited |

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📄 License

MIT © javad Sharifi

🙏 Acknowledgments

• Built with TypeScript and React
• Uses decimal.js for precise decimal calculations
• Inspired by the needs of Persian and Arabic speaking developers

📞 Support

• 📧 telegram: Javad Sharifi
• 🐛 Issue Tracker
• 💬 Discussions

Made with ❤️ for the Persian and Arabic developer community