> For AI agents: the complete documentation index is available at https://wallarm.github.io/design-system/llms.txt, the full documentation bundle is available at https://wallarm.github.io/design-system/llms-full.txt.

# FormatNumber

Prints a number the way the house number guide says to: abbreviated by default — `12k`, `59.6M` — with the full figure in a tooltip behind a dashed underline. `type` chooses the family: `decimal`, `percent`, which refuses to round to a flat `0%` or `100%` it has not earned, and `byte`, which counts in units of 1000.

[Source](https://github.com/wallarm/design-system/tree/main/packages/design-system/src/components/FormatNumber) · [Storybook](https://wallarm.github.io/design-system/storybook/?path=/docs/data-display-formatnumber--overview)

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const Compact = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    {compactValues.map(v => (
      <>
        <FormatNumber key={v} value={v} />
      </>
    ))}
  </div>
);
```

## Usage

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';
```

## Examples

### Standard

`notation='standard'` prints the grouped figure instead, for the place where the exact
number is the point and there is room to show it.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const Standard = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    {compactValues.map(v => (
      <>
        <FormatNumber key={v} value={v} notation='standard' />
      </>
    ))}
  </div>
);
```

### With unit

`unit` follows the value — except on an abbreviated number with its tooltip still on,
where it moves into the tooltip and the accessible name and leaves the cell.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const WithUnit = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    <FormatNumber value={42} unit='requests' />
    <FormatNumber value={12_042} unit='requests' />
    <FormatNumber value={59_614_283} unit='errors' />
    <FormatNumber value={500} unit='requests' notation='standard' />
  </div>
);
```

### Percent

The boundary rules: anything above zero that would round to `0%` prints `<1%`, and
anything below a hundred that would round to `100%` prints `>99%`, with `decimals`
moving both thresholds.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const Percent = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    <FormatNumber value={0} type='percent' />
    <FormatNumber value={0.02} type='percent' />
    <FormatNumber value={0.02} type='percent' decimals={1} />
    <FormatNumber value={25.5} type='percent' decimals={1} />
    <FormatNumber value={50} type='percent' />
    <FormatNumber value={99.97} type='percent' />
    <FormatNumber value={99.97} type='percent' decimals={1} />
    <FormatNumber value={100} type='percent' />
  </div>
);
```

### Bytes

`byte` counts in decimal units — a thousand to the kilobyte, not 1024 — so 12,700,000
reads `12.7 MB`, and `standard` spells the whole figure out.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const Bytes = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    <FormatNumber value={512} type='byte' />
    <FormatNumber value={3_400} type='byte' />
    <FormatNumber value={12_700_000} type='byte' />
    <FormatNumber value={2_345_678_901} type='byte' />
    <FormatNumber value={1_100_000_000_000} type='byte' />
    <FormatNumber value={12_700_000} type='byte' notation='standard' />
  </div>
);
```

### No tooltip

`tooltip={false}` removes the tooltip and the dashed underline with it, for a cell where
the abbreviation is enough; the full value stays in the accessible name.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const NoTooltip = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    <FormatNumber value={12_042} tooltip={false} />
    <FormatNumber value={59_614_283} tooltip={false} />
    <FormatNumber value={12_042} unit='requests' tooltip={false} />
    <FormatNumber value={12_700_000} type='byte' tooltip={false} />
  </div>
);
```

### Negative values

Negatives abbreviate on the same tiers, with the sign kept in front of the number.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const NegativeValues = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    <FormatNumber value={-42} />
    <FormatNumber value={-12_042} />
    <FormatNumber value={-59_614_283} />
  </div>
);
```

### Null value

`null` and `undefined` render an em dash with 'No data' on hover, so a figure nobody
recorded never reads as a zero.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const NullValue = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    <FormatNumber value={null} />
    <FormatNumber value={undefined} />
  </div>
);
```

### Special values

Zero is printed as itself rather than abbreviated, while `NaN` and `Infinity` fall back
to the em dash — with no tooltip, since there is nothing behind them to show.

```tsx
import { FormatNumber } from '@wallarm-org/design-system/FormatNumber';

export const SpecialValues = () => (
  <div className='grid grid-cols-[1fr_1fr] items-center gap-x-16 gap-y-12'>
    <FormatNumber value={0} />
    <FormatNumber value={Number.NaN} />
    <FormatNumber value={Number.POSITIVE_INFINITY} />
  </div>
);
```

## Props

| Prop           | Type                                                 | Default   | Description                                                                                                                                                                            |
| -------------- | ---------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| title          | `string \| undefined`                                |           |                                                                                                                                                                                        |
| defaultChecked | `boolean \| undefined`                               |           |                                                                                                                                                                                        |
| defaultValue   | `string \| number \| readonly string[] \| undefined` |           |                                                                                                                                                                                        |
| autoFocus      | `boolean \| undefined`                               |           |                                                                                                                                                                                        |
| id             | `string \| undefined`                                |           |                                                                                                                                                                                        |
| tabIndex       | `number \| undefined`                                |           |                                                                                                                                                                                        |
| rel            | `string \| undefined`                                |           |                                                                                                                                                                                        |
| onChange       | `ChangeEventHandler<T, Element> \| undefined`        |           |                                                                                                                                                                                        |
| value \*       | `number \| null \| undefined`                        |           | Numeric value to display. null/undefined renders em dash + "No data" tooltip.                                                                                                          |
| type           | `FormatNumberType \| undefined`                      | `decimal` | Formatting category. Default: 'decimal'. - 'decimal': plain number with optional abbreviation - 'percent': percentage with boundary safety - 'byte': decimal byte units: 512 B, 2.3 GB |
| notation       | `FormatNumberNotation \| undefined`                  | `compact` | 'compact' abbreviates (12k, 59.6M); 'standard' shows full value. Default: 'compact'. Only applies to type='decimal' and type='byte'.                                                   |
| unit           | `string \| undefined`                                |           | Unit label for accessible name + tooltip: "requests", "errors". Appended after a space. Only meaningful for type='decimal'.                                                            |
| decimals       | `number \| undefined`                                | `0`       | Decimal places for percent. Default: 0.                                                                                                                                                |
| tooltip        | `boolean \| undefined`                               |           | Whether to show a tooltip with the full value on abbreviated numbers. When false, abbreviated values display without tooltip or dashed underline. Default: true.                       |
| data-testid    | `string \| undefined`                                |           |                                                                                                                                                                                        |