# Raqam

> The definitive React number input: live formatting, full i18n, headless, accessible. Zero runtime dependencies, ~2.2 KB core, React 18/19.

Import `NumberField` for the compound components, or `useNumberFieldState`
+ `useNumberField` to own the DOM. Configure formatting on `NumberField.Root`
(`locale`, `formatOptions` — passed to `Intl.NumberFormat`), never on `Input`.
Native `<form>` submission needs `name` on `Root` plus `<NumberField.HiddenInput />`,
because the visible input holds the formatted string. Typing non-Latin digits
needs a side-effect import: `import "raqam/locales/fa"` (also `ar`, `bn`, `hi`, `th`).

## Start here

- [Getting Started](https://raqam.47vigen.com/api/md/getting-started): Install raqam and build your first number field in under five minutes.
- [Overview](https://raqam.47vigen.com/api/md): The definitive React number input — live formatting, full i18n, headless, accessible.
- [Playground](https://raqam.47vigen.com/api/md/playground): Edit runnable examples in the browser — the sandbox installs the same raqam package as npm.

## API reference

- [Advanced Primitives](https://raqam.47vigen.com/api/md/api/advanced-primitives): Lower-level hooks and context exports for design-system authors and custom number field primitives.
- [Core Utilities](https://raqam.47vigen.com/api/md/api/core-utilities): Low-level formatting, parsing, locale registration, and caret helpers from raqam/core and raqam/server.
- [Format Presets](https://raqam.47vigen.com/api/md/api/presets): Named Intl.NumberFormatOptions configurations for common number input patterns.
- [NumberField Components](https://raqam.47vigen.com/api/md/api/components): Headless compound components — the fastest way to build a number field.
- [useNumberFieldFormat](https://raqam.47vigen.com/api/md/api/use-number-field-format): Lightweight display-only formatting hook — no input state machine overhead.
- [useNumberFieldState](https://raqam.47vigen.com/api/md/api/use-number-field-state): State management hook for number fields — use when building the Hook API pattern.
- [useNumberField](https://raqam.47vigen.com/api/md/api/use-number-field): Behavior hook — generates ARIA props, keyboard handlers, and event handlers for a number field.

## Guides

- [Accessibility](https://raqam.47vigen.com/api/md/guides/accessibility): WAI-ARIA spinbutton role, keyboard navigation, and screen reader behaviour.
- [Formatting & Input Behavior](https://raqam.47vigen.com/api/md/guides/formatting): How raqam formats while you type — the cursor algorithm, intermediate states, paste/copy, smart editing, clamping, and notation handling.
- [Locales & i18n](https://raqam.47vigen.com/api/md/guides/locales): Using raqam with non-Latin digit systems — Persian, Arabic, Bengali, Hindi, Thai.
- [Next.js App Router](https://raqam.47vigen.com/api/md/guides/nextjs): Using raqam with Next.js App Router — client components, Server Components, and edge functions.
- [RTL Support](https://raqam.47vigen.com/api/md/guides/rtl): How raqam renders right-to-left number inputs for Arabic, Persian, Hebrew, and Urdu.

## Recipes

- [Financial App](https://raqam.47vigen.com/api/md/recipes/financial): Accounting format, fixed decimal scale, arbitrary precision, and currency conversion.
- [Formik](https://raqam.47vigen.com/api/md/recipes/formik): Integrating raqam with Formik using the useFormik hook or Field component.
- [Persian E-commerce](https://raqam.47vigen.com/api/md/recipes/persian-ecommerce): Building number inputs for Persian-language e-commerce — toman currency, RTL, and native digit support.
- [Tailwind CSS](https://raqam.47vigen.com/api/md/recipes/tailwind): Styling raqam with Tailwind CSS — data attributes, focus rings, and dark mode.
- [react-hook-form](https://raqam.47vigen.com/api/md/recipes/react-hook-form): Integrating raqam with react-hook-form using the Controller pattern.
- [shadcn/ui](https://raqam.47vigen.com/api/md/recipes/shadcn-ui): Wrapping raqam with shadcn/ui primitives for a polished, design-system-consistent number input.

## Optional

- [Full documentation, inlined](https://raqam.47vigen.com/llms-full.txt): every page above as one file
- [Repository](https://github.com/47vigen/raqam): source, issues, and an installable agent skill under `skills/raqam`
- [AGENTS.md](https://github.com/47vigen/raqam/blob/main/AGENTS.md): conventions for agents working in this repo