<Currency>

Overview

The <Currency> component renders a numerical value as a currency. The number is formatted based on the current locale and any optional parameters passed. The currency component only handles formatting and does not perform any exchange rate calculations.

<Currency>{100}</Currency>
// Output: $100.00

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`
`currency?`	`string`	`"USD"`
`options?`	`Intl.NumberFormatOptions`	`{}`
`locales?`	`string[]`	`undefined`

Description

Prop	Description
`children`	The content to render inside the component. Typically a number representing the value to be formatted as currency. If provided, it takes precedence over the `value` prop.
`name`	Optional name for the currency field, used for metadata purposes.
`value`	The default value for the currency. Will fallback to children if not provided. Can be a string or number. Strings will be parsed into numbers before formatting.
`currency`	The currency type, such as "USD" or "EUR". This determines the symbol and formatting used for the currency.
`options`	Optional formatting options for the currency, following the `Intl.NumberFormatOptions` specification. Use this to define styles such as maximum fraction digits, grouping, 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 currency as a string.

Examples

Basic example

The <Currency> component can be used to display localized currency values.

PriceDisplay.jsx

import { Currency } from 'gt-react'; 
 
export default function PriceDisplay(item) {
    return (
        <Currency> {item.price} </Currency> 
    );
}

Specifying currency

Here we are displaying the price in Euros.

PriceDisplay.jsx

import { Currency } from 'gt-react';
 
export default function PriceDisplay(item) {
  return (
    <Currency currency="EUR"> {item.price} </Currency> 
  );
}

Translating `<Currency>` components

Say that you want the currency to be displayed in a sentence that is also translated. You can wrap the <Currency> component in a <T> component.

PriceDisplay.jsx

import { T, Currency } from 'gt-react';
 
export default function PriceDisplay(item) {
  return (
    <T id="itemPrice">
      The price is <Currency> {item.price} </Currency>.
    </T> 
  );
}

Custom formatting

Here we are displaying the price in GBP that specifies exactly decimal places and uses the narrow symbol for the currency (i.e., "$100" rather than "US$100"). Read more about the Intl.NumberFormatOptions for more options.

PriceDisplay.jsx

import { Currency } from 'gt-react';
 
export default function PriceDisplay(item) {
  return (
    <Currency
      currency="GBP"
      options={{ 
        currencyDisplay: 'narrowSymbol', 
        minimumFractionDigits: 2, 
        maximumFractionDigits: 2, 
      }} 
    >
      {item.price}
    </Currency>
  );
}

Dictionary Examples

The <Currency> component can also be used in a dictionary entry. All of the above formatting can also be applied when using a dictionary.

Basic dictionary example

dictionary.jsx

import { Currency } from 'gt-react';
 
const dictionary = {
    "itemPrice": <>
        The price is <Currency>{10}</Currency>.
    </>,
};
export default dictionary;

PriceDisplay.jsx

import { useGT } from 'gt-react';
 
export default function PriceDisplay(item) {
    const t = useGT();
    return (
        <div>
            { t('itemPrice') }
        </div>
    );
}

Passing values to dictionary entries

When you want to pass values from a component to a dictionary entry, you have to define a name for the <Currency> component and then reference the name when you call the t() function.

dictionary.jsx

import { Currency } from 'gt-react';
 
const dictionary = {
    "itemPrice": <>The price is <Currency name='price'/>.</>, 
};
export default dictionary;

PriceDisplay.jsx

import { useGT } from 'gt-react';
 
export default function PriceDisplay(item) {
  const t = useGT();
  return (
    <div>
      { t('itemPrice', { price: item.price }) }
    </div>
  );
}

Notes

The <Currency> component is used to format currency values based on the current locale and any optional parameters passed.
The currency component only handles formatting and does not perform any exchange rate calculations.
The contents of the <Currency> component will not be sent to the API for translation. All reformatting is done locally using the Intl.NumberFormat library.

Next Steps

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

<Currency>

On this page