# Vue: `<Num>`
URL: https://generaltranslation.com/en-US/docs/vue/reference/components/num.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Format a number for the active locale. API reference for the `<Num>` component.

The `<Num>` component formats a required numeric `value` with `Intl.NumberFormat`. Use it on its own or as a runtime variable inside [`<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-US: 1,234.5 -->
```

Formatting happens locally. The numeric value is not translated or 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 and ignores `locales`. At 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. 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 with `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'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'` |
| `currencySign` | Standard or accounting notation for negative currency values. | `'standard' \| 'accounting'` | Yes | `'standard'` |
| `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 \| 'auto' \| 'always' \| 'min2'` | 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. | `'ceil' \| 'floor' \| 'expand' \| 'trunc' \| 'halfCeil' \| 'halfFloor' \| 'halfExpand' \| 'halfTrunc' \| 'halfEven'` | Yes | `'halfExpand'` |
| `roundingPriority` | Resolves conflicts between fraction and significant-digit settings. | `'auto' \| 'morePrecision' \| 'lessPrecision'` | Yes | `'auto'` |
| `roundingIncrement` | Rounds to `1`, `2`, `5`, `10`, `20`, `25`, `50`, `100`, `200`, `250`, `500`, `1000`, `2000`, `2500`, or `5000`. | `number` | Yes | `1` |
| `trailingZeroDisplay` | Controls trailing zeros on integer values. | `'auto' \| 'stripIfInteger'` | Yes | `'auto'` |

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>
```

## Sitemap

See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.