useNumberFieldFormat

useNumberFieldFormat formats a number for display using Intl.NumberFormat. It has zero state machine overhead — ideal for price tables, dashboards, or any read-only numeric display.

This is a client hook (it ships with the "use client" directive). In React Server Components, Edge functions, or any non-React code, use createFormatter from raqam/server instead — see Core utilities and the server-side example below.

Import

import { useNumberFieldFormat } from "raqam";
// or
import { useNumberFieldFormat } from "raqam/react";

Signature

function useNumberFieldFormat(
  value: number | null,
  options?: {
    locale?: string;
    formatOptions?: Intl.NumberFormatOptions;
    prefix?: string;
    suffix?: string;
    minimumFractionDigits?: number;
    maximumFractionDigits?: number;
    fixedDecimalScale?: boolean;
  }
): string;

Parameters

Param	Type	Description
`value`	`number \| null`	The value to format. Returns `""` for `null` or non-finite values.
`options.locale`	`string`	BCP 47 locale. Defaults to the current runtime locale.
`options.formatOptions`	`Intl.NumberFormatOptions`	Passed to `Intl.NumberFormat`.
`options.prefix` / `options.suffix`	`string`	Add custom affixes around the formatted value.
`options.minimumFractionDigits` / `options.maximumFractionDigits`	`number`	Override fraction digit behavior.
`options.fixedDecimalScale`	`boolean`	Forces `maximumFractionDigits` trailing zeros.

Return value

A formatted string, or "" when value is null or non-finite (NaN, Infinity).

Example — price table

import { useNumberFieldFormat } from "raqam";

function PriceTag({ amount }: { amount: number }) {
  const formatted = useNumberFieldFormat(amount, {
    locale: "en-US",
    formatOptions: { style: "currency", currency: "USD" },
  });

  return <span>{formatted}</span>;
}

// "en-US" + USD → "$1,234.56"
// "de-DE" + EUR → "1.234,56 €"
// "fa-IR" + IRR → "۱٬۲۳۴٫۵۶ ﷼"

Example — server-side use

For React Server Components or SSR, import from raqam/server (zero React dependency):

import { createFormatter } from "raqam/server";

const formatter = createFormatter({
  locale: "en-US",
  formatOptions: { style: "currency", currency: "USD" },
});

const html = `<span>${formatter.format(1234.56)}</span>`;
// "$1,234.56"

Example — in a table

const items = [
  { name: "MacBook Pro", price: 2499 },
  { name: "iPhone 15 Pro", price: 1199 },
  { name: "AirPods Pro", price: 249 },
];

function PriceTable() {
  return (
    <table>
      {items.map((item) => (
        <PriceRow key={item.name} {...item} />
      ))}
    </table>
  );
}

function PriceRow({ name, price }: { name: string; price: number }) {
  const formatted = useNumberFieldFormat(price, {
    locale: "en-US",
    formatOptions: { style: "currency", currency: "USD" },
  });

  return (
    <tr>
      <td>{name}</td>
      <td style={{ textAlign: "right", fontVariantNumeric: "tabular-nums" }}>
        {formatted}
      </td>
    </tr>
  );
}

vs NumberField.Formatted

	`useNumberFieldFormat`	`NumberField.Formatted`
Use case	Any component, standalone display	Inside a `NumberField.Root`
Requires state	No	Yes (reads from context)
Reflects user edits	No	Yes (live updates with input)

useNumberFieldFormat

On this page