| name | raqam |
| description | Teaches the raqam React number-input library — headless NumberField compound components, useNumberFieldState/useNumberField hooks, Intl presets, locale plugins (fa/ar/bn/hi/th), raqam/server formatting, validation, ScrubArea, accessibility, and form integration. Use when building or debugging currency/percent/unit fields, live-formatted inputs, non-Latin digits, react-hook-form/Formik, Next.js App Router client vs server formatting, or any raqam API. |
raqam (React number input)
Canonical sources (read these for full detail)
Do not assume paths inside the raqam repo; always prefer the docs URLs above. Version in this skill reflects the library at publish time; confirm the current version on npm.
What raqam is
- Live formatting while typing using
Intl.NumberFormat (cursor-safe algorithm; not “format on blur only”).
- Headless: no default styles; compound
NumberField.* or raw hooks.
- i18n: locale-driven separators and symbols; optional locale plugins for non-Latin digits (Persian, Arabic, Bengali, Hindi, Thai).
- Accessibility: WAI-ARIA
spinbutton, aria-valuenow / aria-valuetext, keyboard model (↑↓ Home End PgUp/PgDn, modifiers for step sizes).
Peer dependencies: React 18+ (and react-dom).
Install
npm install raqam
Entry points
| Import | Use for |
|---|
raqam | NumberField, useNumberFieldState, useNumberField, useNumberFieldFormat, presets |
raqam/react | Same hooks/components (alternate entry; see docs) |
raqam/core | No React — createFormatter, createParser, registerLocale, presets |
raqam/server | Alias of raqam/core — safe in RSC, edge, Node (zero React deps) |
raqam/locales/<lang> | Side-effect plugins: fa, ar, bn, hi, th (tree-shakeable) |
raqam/locales | Registers all built-in locale plugins |
Bundle sizes and export map: see README and Getting Started.
Choose an API
Compound components (default) — less boilerplate, context-wired parts:
- Guide: NumberField components
NumberField.Root + Label, Group, Input, Increment/Decrement, Description, ErrorMessage, HiddenInput, ScrubArea, Formatted, etc.
Hook API — full control over DOM and styling:
- useNumberFieldState — state machine (
inputValue, numberValue, rawValue, validation, scrubbing).
- useNumberField — ARIA props + handlers; requires
inputRef to the <input>.
Lower-level helpers — only when building custom primitives or non-React formatting:
- Core utilities —
createFormatter, createParser, normalizeDigits, registerLocale, caret helpers.
- Advanced primitives —
useControllableState, usePressAndHold, useScrubArea, NumberFieldContext, useNumberFieldContext.
Recommended agent path
Use the simplest path that fits the user’s request:
- Default:
NumberField.Root + compound components.
- Need custom DOM or design-system wrappers:
useNumberFieldState + useNumberField.
- Need display-only formatting in React:
useNumberFieldFormat.
- Need formatting/parsing in RSC, SSR, Edge, or non-React code:
raqam/server / raqam/core.
- Need non-Latin digit input: import only the needed locale plugin (
raqam/locales/fa, etc.).
- Need analytics/change metadata: use
onValueChange, not raw onChange.
- Need arbitrary-precision finance flows: use
onRawChange / state.rawValue, or custom parseValue / formatValue.
Avoid steering users toward undocumented or stale APIs when a documented path already exists.
Behavior essentials
locale: BCP 47 tag; drives Intl.NumberFormat / parsing.formatOptions: standard Intl.NumberFormatOptions; use presets for common cases — Format presets.- Controlled vs uncontrolled:
value/onChange vs defaultValue. onChange fires whenever the parsed numeric value changes; use onValueChange when you need { reason, formattedValue } metadata — see Getting Started.
- Constraints:
minValue, maxValue, step, largeStep, smallStep, clampBehavior, allowOutOfRange, allowNegative, allowDecimal, fixedDecimalScale.
- Validation:
validate returning true / error string; pairs with NumberField.ErrorMessage.
- Precision / finance:
onRawChange and state.rawValue for exact string before float conversion; optional custom formatValue / parseValue.
- Display-only: useNumberFieldFormat on the client;
createFormatter from raqam/server on the server.
- Forms: for native form submission, put
name on NumberField.Root and render NumberField.HiddenInput.
Locales and RTL
Next.js
- Next.js App Router —
"use client" for inputs; raqam/server for Server Components and edge-safe formatting.
Forms and UI stacks
Styling and UX
- Root
data-* attributes for CSS include data-focused, data-invalid, data-disabled, data-readonly, data-required, and data-scrubbing.
- The input also exposes
data-rtl for RTL-specific styling.
- ScrubArea: pointer-lock drag to change value — components doc.
render prop on compound parts to swap elements without asChild.
Accessibility
- Accessibility guide —
spinbutton, keyboard table, focus model (Tab targets input; steppers use arrow keys).
Interactive exploration
When the model needs more detail
- Open the exact doc page from the links above (prefer over guessing APIs).
- Use Context7 / current package docs for npm
raqam if behavior vs version matters.
- For exhaustive option tables and extra props, see reference.md.
- For copy-paste patterns, see examples.md.
Docs site map (official)
Recipes are linked from the docs homepage sidebar.
