Skip to content
Home

NumberFormat

Info
Demos
Properties
Provider

Import

import { NumberFormat } from '@dnb/eufemia'

Description

A ready-to-use DNB number formatter. Use it wherever you have to display a number, a currency value, phone number, etc.

Good reasons for why we have this is to:

  • uniform the formation of numbers for all DNB applications.
  • and make numbers accessible to screen readers.

Supported formats

  • Numbers in general e.g.
  • Currency e.g.
  • Percentage e.g.
  • Phone numbers e.g.
  • Bank account number e.g.
  • National identification number e.g.
  • Organization number e.g.
  • Compact (short) numbers e.g.
  • Compact (long) currency e.g.

Defaults

It uses the browser APIs number.toLocaleString or Intl.NumberFormat.format under the hood. As well as some custom formatter. The locale defaults to:

  • Locale: nb-NO
  • Currency: NOK

Norwegian kroner

When the currency format is set to currency_display="name", the currency will be displayed as "kroner" instead of "Norwegian kroner".

  • Norwegian currency:
  • Swedish currency:

Not available

When a number should be displayed, but for some reason is not available to the frontend application, the NumberFormat component will display a single em dash (–) and a screen reader will get a text (Ikke tilgjengelig / Not available).

Example:

Decimals

If the value has more decimal places than specified by the decimals={2} property, it will be rounded accordingly.

Here are the available options for the rounding property:

  • omit truncate decimals without rounding.
  • half-even will round to the nearest even number.
  • half-up (default) will round up if the fractional part is 0.5 or greater, the number is rounded up. If the fractional part is less than 0.5, the number is rounded down.

Provider

You can send down the locale as an application-wide property (Context). More info about the provider and locale usage.

import Provider from '@dnb/eufemia/shared/Provider'


render(
  <Provider locale="en-GB" NumberFormat={{ currency_display: 'code' }}>
    <MyApp>
      text <NumberFormat>123</NumberFormat> table etc.
    </MyApp>
  </Provider>,
)

NumberFormat Hook

Heads up: If you do so, keep in mind, you will have to ensure all the accessibility enhancements the component offers. For that you can use the aria field:

import Provider from '@dnb/eufemia/shared/Provider'
import useNumberFormat from '@dnb/eufemia/components/number-format/useNumberFormat'


function Component() {
  // By using returnAria you get an object
  const { number, aria } = useNumberFormat(12345678.9, {
    // Props are inherited from the Eufemia Provider and the NumberFormat object
    returnAria: true,
  })


  return (
    <span>
      <span aria-hidden>{number}</span>
      <span className="dnb-sr-only">{aria}</span>
    </span>
  )
}


render(
  <Provider locale="en-GB" NumberFormat={{ currency: 'EUR' }}>
    <Component />
  </Provider>,
)

Formatting only (interceptor)

You can use the format method without using a React Component or React Hook.

Heads up: If you do so, keep in mind, you will have to ensure all the accessibility enhancements the component offers. For that you can use the aria field:

import { format } from '@dnb/eufemia/components/number-format/NumberUtils'


// By using returnAria you get an object
const { number, aria } = format(12345678.9, {
  locale: 'nb-NO', // not inherited
  currency: true,
  returnAria: true,
})


// Basic formatting
const number = format(1234)

The format method will accept the same properties as the component.

Interceptor helpers

Also, you may check out the related tests NumberFormat > cleanNumber in the source code to find more examples.

import { cleanNumber } from '@dnb/eufemia/components/number-format/NumberUtils'


const string = cleanNumber('prefix -12 345,678 suffix') // returns -12345.678
const string = cleanNumber('prefix -12.345,678 suffix') // returns -12345.678

Element and style

The number component is style-independent, so it has no visual styles. By default, a <span> is used (with speak-as: numbers, even the support is very low). But you can easily change the element type by providing something else to element="div" property.

Accessibility

NVDA has also issues on reconciling the lang attribute, this makes it hard to have a solid and good solution for reading numbers. VoiceOver on desktop makes a perfect job there.

VoiceOver on mobile devices (iOS) only supports numbers read out properly to a maximum of 99,999.00. On amounts above this value, VO reads numbers digit by digit.

To enhance the Copy & Paste experience of copying numbers into other applications (Excel), you may use the clean_copy_value property – it will then provide a second number, without thousand separators and to have a comma/dot (depending on the locale) as the decimal separator. This number is not visible, but will be used when selecting & copying the whole number on the first click to the system clipboard.

You can enable this feature on all your NumberFormat components by using the Provider:

import { Provider } from '@dnb/eufemia/shared'


render(
  <Provider value={{ NumberFormat: { clean_copy_value: true } }}>
    <YourApp />
  </Provider>,
)

More details

Screen readers require numbers to be formatted properly in order to be read as numbers. The NumberFormat component will help to achieve this requirement.

So, numbers are formatted differently for screen readers than the visual number. And numbers also get assigned a lang attribute, so the screen reader knows what language (locale) should be used on the particular number, even if the text around does not correspond to the same language.

Sources

Eufemia is basing their number formats on both the Norwegian authority and Språkradet, and currency is based on guidelines from Språkrådet. Wikipedia has more info on world wide decimal separator usage.

For international number formatting, we use the EU Style Guide.

Node.js and SSR usage

If you run the component or format function in Node.js you have to include ICU data in order to display other locales than en-GB. You can do this by:

  • installing npm i full-icu
  • and call node (or jest) with an environment variable pointing to the package: NODE_ICU_DATA=./node_modules/full-icu node ...
  • after a Node.js version upgrade you may have to run npm rebuild

Known issues

Edge Browser on Windows 10 is converting numbers automatically to followable links. This makes the experience on NVDA bad, as it reads also the new, unformatted link number.

You can disable this behavior:

<html x-ms-format-detection="none">
  ...
</html>

Lighthouse and axe-core

In order to enhance the UX while using a screen reader, the NumberFormat component is using a role called role="text". This allows the screen reader to read particular numbers within the context, without interrupting the flow while reading paragraphs.

Lighthouse is using axe-core under the hood. Older versions of axe-core is allowing us to use role="text" only within no focusable descendants. But because the NumberFormat component also includes a Copy & Paste feature, it uses tabindex="-1" which allows JavaScript to focus the descendant DOM Element.