# vue: <Num>
URL: https://generaltranslation.com/en-GB/docs/vue/reference/components/num.mdx
---

title: "<Num>"
description: Format a number for the active locale. API reference for the <Num> component.

---

The `<Num>` component formats a required numeric `value` using `Intl.NumberFormat`. Use it on its own or as a runtime variable within [`<T>`](/docs/vue/reference/components/t).

## Overview [#overview]

Bind the number through `value` and keep the component self-closing:

```vue
<Num :value="1234.5" />
<!-- en-GB: 1,234.5 -->
```

Formatting is performed locally. The numeric value is neither translated nor included in the rich translation source.

## How it works [#how-it-works]

* A number is passed directly to `Intl.NumberFormat`.
* A string must represent an entire number. Whitespace-only strings and `null` render empty; an invalid numeric string renders unchanged.
* Formatter slot children are ignored. Always provide `value` and use a self-closing tag.
* The component adds no HTML wrapper.

### Locale resolution

When the active locale is the configured default locale, formatting uses only that default locale and ignores `locales`. For any other active locale, a standalone formatter tries explicit `locales` first, then the active locale, and finally the default locale. Duplicate locales are removed without changing their order.

Inside [`<T>`](/docs/vue/reference/components/t), the rich translation controls formatting: source fallback content uses the default locale, while translated content tries the active locale and then the default locale. An explicit `locales` prop is ignored in that case.

## Props [#props]

| Prop                  | Description                               | Type                       | Optional | Default                 |
| --------------------- | ----------------------------------------- | -------------------------- | -------- | ----------------------- |
| [`value`](#value)     | Numeric value to format.                  | `number \| string \| null` | No       | —                       |
| [`options`](#options) | Options forwarded to `Intl.NumberFormat`. | `Intl.NumberFormatOptions` | Yes      | `{}`                    |
| [`locales`](#locales) | Preferred formatting locales.             | `string[]`                 | Yes      | Locale resolution order |

### `value`

**Type** `number | string | null` · **Required**

The complete numeric value to format. Numeric strings are converted using `Number()` before formatting. Values such as `"12 items"` or `"1,234.5"` are not partially parsed and render unchanged.

```vue
<Num :value="item.quantity" />
```

### `options`

**Type** `Intl.NumberFormatOptions` · **Optional** · **Default** `{}`

Options forwarded to the JavaScript runtime&#39;s `Intl.NumberFormat` implementation. Common options include:

| Option                     | Description                                                  | Type                                                          | Optional | Default            |
| -------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------- | -------- | ------------------ |
| `localeMatcher`            | Locale matching algorithm.                                   | `'lookup' \| 'best fit'`                                      | Yes      | `'best fit'`       |
| `numberingSystem`          | Numbering system, such as `latn` or `arab`.                  | `string`                                                      | Yes      | Locale-dependent   |
| `style`                    | Decimal, percent, currency or unit formatting.               | `'decimal' \| 'percent' \| 'currency' \| 'unit'`              | Yes      | `'decimal'`        |
| `currency`                 | ISO 4217 code required by currency style.                    | `string`                                                      | Yes      | —                  |
| `currencyDisplay`          | How a currency is displayed.                                 | `'code' \| 'symbol' \| 'narrowSymbol' \| 'name'`              | Yes      | `'symbol'`         |
| `unit`                     | Unit identifier required by unit style, such as `kilometer`. | `string`                                                      | Yes      | —                  |
| `unitDisplay`              | Width of the unit label.                                     | `'long' \| 'short' \| 'narrow'`                               | Yes      | `'short'`          |
| `minimumIntegerDigits`     | Minimum integer digits.                                      | `number`                                                      | Yes      | `1`                |
| `minimumFractionDigits`    | Minimum fraction digits.                                     | `number`                                                      | Yes      | Style-dependent    |
| `maximumFractionDigits`    | Maximum fraction digits.                                     | `number`                                                      | Yes      | Style-dependent    |
| `minimumSignificantDigits` | Minimum significant digits.                                  | `number`                                                      | Yes      | `1`                |
| `maximumSignificantDigits` | Maximum significant digits.                                  | `number`                                                      | Yes      | `21`               |
| `useGrouping`              | When to display grouping separators.                         | `boolean \| string`                                           | Yes      | Notation-dependent |
| `notation`                 | Number notation.                                             | `'standard' \| 'scientific' \| 'engineering' \| 'compact'`    | Yes      | `'standard'`       |
| `compactDisplay`           | Compact-notation label width.                                | `'short' \| 'long'`                                           | Yes      | `'short'`          |
| `signDisplay`              | When to display a sign.                                      | `'auto' \| 'always' \| 'exceptZero' \| 'negative' \| 'never'` | Yes      | `'auto'`           |
| `roundingMode`             | Direction used when rounding.                                | `string`                                                      | Yes      | Runtime-dependent  |

Fraction-digit defaults depend on the selected `style`. Supported fields and values can also vary by JavaScript runtime. See the [`Intl.NumberFormat` options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/NumberFormat/NumberFormat#options) for the complete runtime-defined set.

### `locales`

**Type** `string[]` · **Optional** · **Default** Locale resolution order

Preferred BCP 47 locale codes for standalone formatting. These are tried before the active and default locales only when the active locale is not the configured default.

```vue
<Num :value="1234.5" :locales="['de-DE']" />
```

## Examples [#examples]

```vue title="InventorySummary.vue"
<script setup lang="ts">
import { Num, T } from 'gt-vue';

defineProps<{ count: number; completionRate: number }>();
</script>

<template>
  <T>There are <Num :value="count" /> units available.</T>
  <p><Num :value="completionRate" :options="{ style: 'percent' }" /> complete</p>
</template>
```