Components

Numeral

Numeral is a primitive component used to format numbers according to our number formatting guidelines.

Please refer to our number formatting guidelines for more detailed information on how we format numbers.

import { Numeral } from '@sproutsocial/racine'
<Box display='flex' justifyContent='center'>
<Numeral number={123456.789} invalidNumberLabel='Not Available' />
</Box>

By default, Numeral will abbreviate numbers (when necessary). When numbers are abbreviated, a tooltip will be added to show the full number. If you'd like to turn this off, set the abbreviate prop to false.

<Box display='flex' justifyContent='center'>
<Numeral number={123456.789} abbreviate={false} />
</Box>

When the number prop is not a valid number, Numeral will automatically render an em dash to represent a null value. Always provide an invalidNumberLabel prop to Numeral so that a text alternative for screen reader users will be added to any null values.

<Box display='flex' justifyContent='center'>
<Numeral number={null} invalidNumberLabel='Not Available' />
</Box>

Properties

NameTypeDefaultDescriptionRequired?
numbernumber
The number to be formatted
localestring
Locale to format. See https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl#locales_argument
format
'decimal'
'currency'
'percent'
currencystring
The currency format to use when formatting currency
abbreviate
boolean
number
A boolean determining whether or not the number should be abbreviated, or a number representing the abbreviation threshold
precision
number
'none'
Override the default decimal precision (2 for decimals/currency, 1 for percentages), or "none" allowing unrestricted precision.
invalidNumberLabelstring
Text to be read off by screen readers for invalid values (i.e., any value rendered as '—' (em dash))
qaObject

Note: This component uses the Text component under the hood, and accepts all of the props of that component in addition to those listed above.

Recipes

Currencies

When format is set to currency, you can provide a currency code to the currency prop to get the proper formatting. This only works when abbreviation is turned off.

<Box display='flex' justifyContent='space-around'>
<Numeral number={123456.789} format='currency' abbreviate={false} invalidNumberLabel='Not Available' />
<Numeral number={123456.789} format='currency' currency='EUR' locale='de-DE' abbreviate={false} invalidNumberLabel='Not Available' />
<Numeral number={123456.789} format='currency' currency='JPY' locale='ja' abbreviate={false} invalidNumberLabel='Not Available' />
</Box>

Percentages

<Box display='flex' justifyContent='center'>
<Numeral number={12.34} format='percent' invalidNumberLabel='Not Available' />
</Box>