<Num>

Overview

The <Num> component renders a formatted number string in the user's locale, and can be customized with formatting options.

<Num>{100}</Num>
// Output: 100

All reformatting is handled locally using the Intl.NumberFormat library.

Reference

Props

Prop	Type	Default
`children?`	`any`	`undefined`
`name?`	`string`	`undefined`
`value?`	`string \| number`	`undefined`
`options?`	`Intl.NumberFormatOptions`	`{}`
`locales?`	`string[]`	`undefined`

Description

Prop	Description
`children`	The content to render inside the component. Typically a number, which will be formatted according to the current locale and options. If provided, it takes precedence over the `value` prop.
`name`	Optional name for the number field, used for metadata purposes.
`value`	The default value for the number. Can be a string or number. Strings will be parsed into numbers before formatting.
`options`	Optional formatting options for the number, following the `Intl.NumberFormatOptions` specification. Use this to define styles such as currency, decimal precision, etc.
`locales`	Optional locales to specify the formatting locale. If not provided, the default user's locale is used. Read more about specifying locales here.

Returns

JSX.Element containing the formatted number as a string.

Examples

Basic Example

In this example, item.quantity will be reformatted according to the user's locale.

QuantityDisplay.jsx

import { Num } from 'gt-next';
 
export default function Inventory(item) {
  return (
    <Num> {item.quantity} </Num>  
  );
}

Specifying locales

By default, locales are determined by the user's browser settings, but you can explicitly set the locale for the <Num> component.

PriceDisplay.jsx

import { Num } from 'gt-next';
 
export default function CountDisplay(item) {
  return (
    <Num locales={['fr-FR']}> {item.count} </Num> 
  );
}

Translating `<Num>` components

Let's say that you want your number to be in a larger sentence that gets translated. Just add the <T> components around the content.

DynamicPriceDisplay.jsx

import { T, Num } from 'gt-next';
 
export default function DynamicPriceDisplay(item) {
  return (
    <T id="price">
      There are <Num> {item.count} </Num> units available.
    </T>
  );
}

Custom formatting

<Num> uses the Intl.NumberFormat library for formatting.

import { Num } from 'gt-next';
 
export default function CustomFormat(number) {
  return (
    <Num
      options={{ style: "decimal", maximumFractionDigits: 2 }}
    >
      {number}
    </Num>
  );
}

Dictionary examples

The <Num> component can also be used in a dictionary entry.

Basic usage

dictionary.jsx

import { Num } from 'gt-next';
 
const dictionary = {
  itemCount: <>You have <Num>1</Num> item.</>
}
export default dictionary;

ItemCount.jsx

import { useGT } from 'gt-next';
 
export default function ItemCount({ count }) {
  const t = useGT();
  return (
    <>{t('itemCount')}</>
  );
}

Passing values to dictionary entries

If you want to pass values to the dictionary entry, you must specify a name for the <Num> component and reference it when calling the t() function.

dictionary.jsx

import { Num } from 'gt-next';
 
const dictionary = {
  itemCount: <>You have <Num name='count'/> item(s).</>
}
export default dictionary;

ItemCount.jsx

import { useGT } from 'gt-next';
 
export default function ItemCount({ count }) {
  const t = useGT();
  return (
    <>{t('itemCount', { count: 1 })}</>
  );
}

Notes

The <Num> component is used to format numbers according to a user's locale.
When inside of a <T> component, make sure to wrap all dynamic numbers in a <Num> component.

Next steps

For more details and usage examples of the <Num> component and other variable components like <Currency>, <DateTime>, and <Var>, see the Using Variable Components documentation.

<Num>

On this page