raqam

Raqam

The definitive React number input: live formatting, full i18n, headless, accessible.

Why raqam?

Feature	Base UI	React Aria	Mantine	raqam
Live formatting while typing	blur	blur
Truly headless
i18n digit input (Persian ۱۲۳, Arabic ١٢٣…)
WAI-ARIA spinbutton
Bundle size	~10 KB	~30 KB	~60 KB	~2.2 KB core

No existing package combines all four. raqam does.

Installation

npm install raqam
# or
pnpm add raqam

Peer dependencies: React 18 or 19.

Quick start

Hook API

import { useNumberFieldState, useNumberField, type UseNumberFieldStateOptions } from 'raqam'
import { useRef } from 'react'

function PriceInput() {
  // Share one options object — useNumberField builds its own formatter/parser,
  // so it needs the same formatting options as useNumberFieldState. `satisfies`
  // keeps the literal types (e.g. style: 'currency') in a strict TS project.
  const options = {
    locale: 'en-US',
    formatOptions: { style: 'currency', currency: 'USD' },
    minValue: 0,
    defaultValue: 1234.56,
  } satisfies UseNumberFieldStateOptions
  const state = useNumberFieldState(options)
  const inputRef = useRef(null)
  const { inputProps, labelProps, incrementButtonProps, decrementButtonProps } =
    useNumberField({ ...options, label: 'Price' }, state, inputRef)

  return (
    <div>
      <label {...labelProps}>Price</label>
      <button {...decrementButtonProps}>−</button>
      <input ref={inputRef} {...inputProps} />
      <button {...incrementButtonProps}>+</button>
    </div>
  )
}

Headless Component API

import { NumberField } from 'raqam'

function PriceField() {
  return (
    <NumberField.Root
      locale="en-US"
      formatOptions={{ style: 'currency', currency: 'USD' }}
      defaultValue={1234.56}
      minValue={0}
      onValueChange={(value, { reason }) => console.log(value, reason)}
    >
      <NumberField.Label>Price</NumberField.Label>
      <NumberField.Group>
        <NumberField.Decrement>−</NumberField.Decrement>
        <NumberField.Input />
        <NumberField.Increment>+</NumberField.Increment>
      </NumberField.Group>
      <NumberField.Description>Enter the product price</NumberField.Description>
      <NumberField.ErrorMessage />
    </NumberField.Root>
  )
}

Format presets

import { presets, NumberField } from 'raqam'

<NumberField.Root formatOptions={presets.currency('USD')} />           // $1,234.56
<NumberField.Root formatOptions={presets.accounting('USD')} />         // (1,234.56)
<NumberField.Root formatOptions={presets.percent} />                   // 12.3%
<NumberField.Root formatOptions={presets.compact} />                   // 1.2K
<NumberField.Root formatOptions={presets.scientific} />                // 1.23E3
<NumberField.Root formatOptions={presets.integer} />                   // 1,234
<NumberField.Root formatOptions={presets.financial} fixedDecimalScale /> // 1,234.00
<NumberField.Root formatOptions={presets.unit('kilometer-per-hour')} /> // 120 km/h

Locales & i18n

Persian input with native digits — just import the plugin and set the locale:

import 'raqam/locales/fa'  // registers ۰–۹ digit normalization (< 200 B)
import { NumberField } from 'raqam'

<NumberField.Root
  locale="fa-IR"
  formatOptions={{ style: 'currency', currency: 'IRR' }}
  suffix=" تومان"
/>
// user types ۱۲۳۴, raqam parses and formats it correctly in real-time

Supported scripts: Persian fa, Arabic ar, Bengali bn, Hindi hi, Thai th. RTL is auto-detected and handled.

Custom validation

<NumberField.Root
  minValue={0}
  validate={(value) => {
    if (value === null) return 'Required'
    if (value % 2 !== 0) return 'Must be an even number'
    return true
  }}
>
  <NumberField.Input />
  <NumberField.ErrorMessage /> {/* auto-renders the validate() error string */}
</NumberField.Root>

Display-only formatting

import { useNumberFieldFormat } from 'raqam'

function PriceDisplay({ price }: { price: number }) {
  const formatted = useNumberFieldFormat(price, {
    locale: 'en-US',
    formatOptions: { style: 'currency', currency: 'USD' },
  })
  return <span>{formatted}</span>  // "$1,234.56"
}

Works in React Server Components too via raqam/server:

import { createFormatter } from 'raqam/server'  // zero React deps

const formatter = createFormatter({
  locale: 'en-US',
  formatOptions: { style: 'currency', currency: 'USD' },
})
const displayPrice = formatter.format(1234.56)  // "$1,234.56"

SSR / hydration notes

• Pin locale for SSR. With no locale, formatting uses the runtime default — the browser locale on the client but the host's ICU/OS locale on the server. If they differ, the server-rendered value won't match the first client render and React logs a hydration mismatch. Pass an explicit locale (the same on both sides) whenever you server-render an initial value.
• Label/description ARIA wires up after mount. <NumberField.Label> is associated with the input via the native htmlFor/id in the SSR HTML (screen readers honor it), but the redundant aria-labelledby (and aria-describedby for <NumberField.Description>) are attached on the client after the label/description registers — they appear post-hydration, not in the static HTML.

ScrubArea (drag to change value)

<NumberField.Root defaultValue={50} minValue={0} maxValue={100}>
  <NumberField.ScrubArea direction="horizontal" pixelSensitivity={2}>
    <NumberField.Label>Opacity</NumberField.Label>
    <NumberField.ScrubAreaCursor>⟺</NumberField.ScrubAreaCursor>
  </NumberField.ScrubArea>
  <NumberField.Input />
</NumberField.Root>

Uses the Pointer Lock API so the cursor never hits the screen edge during drag.

CSS styling with data attributes

/* All state-based styling — no JS needed */
[data-focused]   { outline: 2px solid blue; }
[data-invalid]   { border-color: red; }
[data-disabled]  { opacity: 0.5; }
[data-readonly]  { background: #f5f5f5; }
[data-required]  { /* required-field styling */ }
[data-scrubbing] { cursor: ew-resize; }
[data-rtl]       { /* RTL-specific overrides (set on the input element) */ }

data-focused, data-invalid, data-disabled, data-readonly, data-required, and data-scrubbing are set on NumberField.Root; data-rtl (plus the state attributes) is set on the NumberField.Input element.

react-hook-form integration

import { Controller } from 'react-hook-form'
import { NumberField } from 'raqam'

<Controller
  name="price"
  control={control}
  render={({ field, fieldState }) => (
    <NumberField.Root
      value={field.value}
      onChange={field.onChange}
      onBlur={field.onBlur}
      validate={() => fieldState.error?.message ?? true}
    >
      <NumberField.Label>Price</NumberField.Label>
      <NumberField.Input />
      <NumberField.ErrorMessage />
    </NumberField.Root>
  )}
/>

Arbitrary-precision string mode

For financial apps that need to avoid IEEE 754 float rounding:

<NumberField.Root
  onRawChange={(rawValue) => {
    // rawValue is the unformatted, precision-preserving numeric string
    // (grouping / currency / prefix / suffix stripped, locale decimal
    // normalized to ".", typed trailing zeros kept) — full precision beyond
    // JS float. e.g. "0.1000000001" — feed it to your BigDecimal library
    myDecimal.set(rawValue)
  }}
/>

Also available as state.rawValue from the hook API.

Custom formatter / parser

import Decimal from 'decimal.js'

<NumberField.Root
  formatValue={(value) => new Decimal(value).toFixed(8)}
  parseValue={(input) => {
    try {
      return { value: new Decimal(input).toNumber(), isIntermediate: false }
    } catch {
      return { value: null, isIntermediate: input.endsWith('.') }
    }
  }}
/>

API Reference

useNumberFieldState(options)

State management hook — returns NumberFieldState.

Prop	Type	Default	Description
value	number | null	—	Controlled value
defaultValue	number | null	—	Uncontrolled default
onChange	(value: number | null) => void	—	Fires whenever the parsed numeric value changes
onRawChange	(raw: string | null) => void	—	Fires with raw unformatted string
locale	string	browser	BCP 47 locale tag
formatOptions	Intl.NumberFormatOptions	{}	Full Intl options
minValue	number	—	Minimum value
maxValue	number	—	Maximum value
step	number	1	Arrow key step
largeStep	number	step × 10	Shift+Arrow step
smallStep	number	step × 0.1	Ctrl/Meta+Arrow step
clampBehavior	"blur" | "strict" | "none"	"blur"	When to clamp to min/max
allowNegative	boolean	true	Allow negative values
allowDecimal	boolean	true	Allow decimal values
fixedDecimalScale	boolean	false	Always show max decimal places
allowOutOfRange	boolean	false	Skip clamping (server-side validation)
validate	(v: number | null) => boolean | string | null	—	Custom validation
prefix	string	—	String prefix (e.g. "$")
suffix	string	—	String suffix (e.g. " تومان")
liveFormat	boolean	true	Format while typing (disable for IME locales)
disabled	boolean	false	Disable the field
readOnly	boolean	false	Read-only mode
required	boolean	false	Mark the field as required

Also accepts maximumFractionDigits, minimumFractionDigits, formatValue, and parseValue — see the full options reference.

useNumberField(props, state, inputRef)

Behavior hook — returns NumberFieldAria prop objects for each element. Accepts every useNumberFieldState option plus the behavior-only props below:

Prop	Type	Default	Description
allowMouseWheel	boolean	false	Mouse wheel to increment/decrement
copyBehavior	"formatted" | "raw" | "number"	"formatted"	Clipboard content on copy
stepHoldDelay	number	400	Press-and-hold initial delay (ms)
stepHoldInterval	number	200	Press-and-hold repeat interval (ms)
label / name / id / aria-*	string	—	Labelling, form name, and id wiring

→ Full reference: useNumberField.

NumberField.Root extra props

Prop	Type	Description
onValueChange	(value, { reason, formattedValue }) => void	Fires on every change, with the change reason
onValueCommitted	(value, { reason }) => void	Fires only on commit (reason: "blur" | "keyboard")
className / style	string / CSSProperties	Applied to the root wrapper <div>

useNumberFieldFormat(value, options)

Display-only formatting hook (client-only — it carries "use client"). Returns a formatted string with zero state overhead. For React Server Components, SSR, or Edge, use createFormatter from raqam/server instead (shown above).

NumberField.* components

Component	Description
Root	Context provider + state orchestration
Label	<label> with correct htmlFor wiring
Group	<div role="group"> for input + buttons
Input	<input type="text" role="spinbutton"> with live formatting
Increment	Increment button with press-and-hold acceleration
Decrement	Decrement button with press-and-hold acceleration
HiddenInput	Hidden <input> for native FormData submission
ScrubArea	Pointer Lock drag-to-adjust area
ScrubAreaCursor	Custom cursor rendered during pointer lock
Description	Help text linked via aria-describedby
ErrorMessage	Error display with role="alert"
Formatted	Read-only formatted value display span

Every component accepts a render prop for element replacement:

<NumberField.Increment render={<MyIconButton />}>▲</NumberField.Increment>
// or with state access:
<NumberField.Increment render={(props, state) => (
  <MyBtn disabled={!state.canIncrement} {...props} />
)} />

Bundle size

Measured min + brotli (including dependencies), enforced in CI via .size-limit.json:

Entry	Size	CI budget
raqam/core	~2.23 KB	2.5 KB
raqam (hooks + components)	~9.62 KB	12 KB
raqam/react	~9.42 KB	10 KB
raqam/locales/fa	196 B	0.3 KB

License

MIT