Currency value

Currency value in Storybook

Usage

This is a utility component for rendering and formatting data, so there are no specific UX guidelines.

Code

<CurrencyValue value={123456} />

Import statement

import { CurrencyValue } from '@jutro/components';

Component contract

Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.

Properties

idrequired

Type

string

Description

Unique identifier for the component.

amount

Type

number | string

Description

The numeric value to display. Equivalent to the amount property in an object entered in the value property.

className

Type

string

Description

CSS class name for this component.

currency

Type

string

Description

The currency name to display for localization. Equivalent to the currency property in an object entered in the value property.

currencyDisplay

Type

'code' | 'symbol' | 'name'

Description

The format of the currency name to display for localization.

Default value

symbol

path

Type

string

Description

Specifies the path to the value used to generate the output.

placeholder

Type

IntlMessageShape

Description

The string to display in the UI if amount is undefined/null.

Default value

'-'

prefix

Type

IntlMessageShape

Description

Optional prefix message to be attached in front of the value.

showFractions

Type

boolean

Description

If true, displays fractions with the amount. If false, it will round the value to the nearest whole number.

Default value

true

showGrouping

Type

boolean

Description

If true, displays grouping separators with the value.

Default value

true

suffix

Type

IntlMessageShape

Description

Optional suffix message to be attached at the end of the value.

tag

Type

string

Description

The HTML tag to use when rendering the outermost element of this component.

Default value

'div'

value

Type

number | string | { amount: number | string, currency: string }

Description

Value to display. If the type is number', it will be used as the currencyamount. If the type is 'string', it will be cast to 'number', then used as currencyamount. If the type is an object, it will set thecurrencyandamount`.

Imperative API

jutro-components offers the formatCurrency function for use with the imperative formatting API.

import { formatCurrency } from '@jutro/components';

This imports a function formatCurrency(intl, props, currencyObject) with the following arguments and return type:

Return value

Type

string

Description

Formatted currency string.

currencyObject

Type

number | string | { amount: number | string, currency: string }

Description

Currency value override to be used instead of the one provided with props.

intl

Type

react.intl.Intl

Description

An instance of the imperative formatting API access object.

props

Type

CurrencyValue.propTypes

Description

Valid properties for a CurrencyValue object.

Hooks

No hooks are available for currency value.

Translation keys

There are no translations for currency value.

For information on how to manage translations, see our section about Internationalization.

Escape hatches

For more information, see our documentation about escape hatches.

Examples

Check out the Usage section for details about how to design a currency value properly, and the different configuration options we provide.

Basic currency value example

The CurrencyValue component can take a numeric value and render it as a monetary amount. It will add a currency symbol, separators, and a decimal separator based on the locale.

<CurrencyValue value={123456} />

Object input example

The value property can take an object that states the amount and currency of the value to display. The currency property needs to be an ISO 4217 alphabetic currency code.

<CurrencyValue value={ {amount: 123456, currency: "EUR"} } />
<CurrencyValue value={ {amount: 123456, currency: "USD"} } />

Amount and currency properties

You can use the amount and currency properties in the CurrencyValue component as an alternative to setting an object in the value property.

<CurrencyValue amount={ 123456 } currency="EUR" />
<CurrencyValue amount={ 123456 } currency="USD" />

Currency format

You can use the currencyDisplay property to set whether to display the symbol, ISO 4217 alphabetic currency code, or name for the currency.

<CurrencyValue value={123456} currencyDisplay="code" />
<CurrencyValue value={123456} currencyDisplay="symbol" />
<CurrencyValue value={123456} currencyDisplay="name" />

Show fractions

You can choose whether to display the fraction part of the value using the showFractions property. This will round the value to the nearest whole number.

<CurrencyValue
  value={1234.5} // note that this becomes 1235 in the sample above due to rounding
  showFractions={false}
/>

Imperative API example

jutro-components offers the formatCurrency function for use with the imperative formatting API.

import { formatCurrency } from '@jutro/components';
import { useIntl } from '@jutro/locale';
...
const intl = useIntl();
...
const c1 = formatCurrency(intl, { value: 1232.24, currency: 'eur', showFractions: true });
const c2 = formatCurrency(intl, { value: 4232.24, currency: 'jpy', showFractions: true, currencyDisplay: 'code'});
const c3 = formatCurrency(intl, { showFractions: true }, { amount: 23434.34, currency: 'dkk' });

// en-US output:
€1,232.24
JPY 4,232
DKK 23,434.34

// pl-PL output
1232,24 €
4232 JPY
23 434,34 DKK

Changelog