# useNumberFormat
URL: /docs/web/hooks/use-number-format

Provider-agnostic number formatting context for Docyrus UI components. Mirror of useDateFormat — wired automatically by DocyrusTenantProvider, but works with any number formatting library.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/hooks-use-number-format
```

The module exports `useNumberFormat()` (hook) and `
  );
}
```

## API Reference

### `useNumberFormat()`

Returns `NumberFormatContextValue`.

| Field | Type | Description |
|-------|------|-------------|
| `formatNumber` | `(value: unknown, options?: NumberFormatOptions) => string` | Formats a number using the active provider's strategy. |

### `NumberFormatOptions`

| Field | Type | Description |
|-------|------|-------------|
| `variant` | `'number' \| 'currency' \| 'percent'` | Output style. Default `'number'`. `'percent'` multiplies the input by 100 and appends `%`. |
| `currency` | `string` | ISO 4217 currency code, used when `variant === 'currency'`. |
| `decimalPrecision` | `number` | Override the locale's default fraction digits. Pass `0` for identifier-like numerics. |
| `thousandSeparator` | `string` | Override the locale's default thousands grouping. Empty string disables grouping. |

### `<NumberFormatProvider>`

| Prop | Type | Description |
|------|------|-------------|
| `formatNumber` | `NumberFormatFn` | Required. The implementation that backs `useNumberFormat()` inside the tree. |
| `children` | `ReactNode` | Tree to wrap. |

### `isDefaultNumberFormatContext(ctx)`

Returns `true` when the value returned by `useNumberFormat()` is the built-in no-provider sentinel (raw `String(value)` renderer) rather than a real provider. Internal hooks use this to avoid shadowing a cell's locale-aware fallback when no provider is mounted. Most apps don't need to call it directly.

## Type Exports

| Type | Description |
|------|-------------|
| `NumberFormatFn` | Signature of the formatter function. |
| `NumberFormatOptions` | Options accepted by `formatNumber`. |
| `NumberFormatContextValue` | Shape returned by `useNumberFormat()`. |