Amount

Component for displaying monetary values

Anatomy

Import and assemble the component:

1import { Amount } from '@raystack/apsara'
2

3<Amount />

API Reference

Formats and displays monetary values with locale and currency support.

Prop

Type

Examples

Basic

1<Flex gap={4}>
2  <Amount value={1299} />
3  <Amount value={1299} currency="EUR" locale="fr-FR" />
4  <Amount value={1299} hideDecimals />
5  <Amount value={1299} currencyDisplay="code" />
6  <Amount value={12.99} valueInMinorUnits={false} />
7  <Amount value={129999999} groupDigits />
8</Flex>

Currency Variants

1<Flex gap={4}>
2  <Amount value={1299} currency="JPY" />
3  <Amount value={1299} currency="BHD" />
4  <Amount value={1299} currency="INR" />
5  <Amount value={1234} minimumFractionDigits={3} maximumFractionDigits={3} />
6</Flex>

valueInMinorUnits

1<Flex gap={4}>
2  <Amount value={1299} valueInMinorUnits /> {/* $12.99 */}
3  <Amount value={12.99} valueInMinorUnits={false} /> {/* $12.99 */}
4</Flex>

locale

1<Flex gap={4}>
2  <Amount value={1299} locale="en-US" /> {/* $12.99 */}
3  <Amount value={1299} currency="EUR" locale="de-DE" /> {/* 12,99 € */}
4  <Amount value={1299} currency="JPY" locale="ja-JP" /> {/* ￥1,299 */}
5</Flex>

hideDecimals

1<Flex gap={4}>
2  <Amount value={1299} hideDecimals /> {/* $12 */}
3  <Amount value={1234} hideDecimals /> {/* $12 */}
4</Flex>

currencyDisplay

1<Flex gap={4}>
2  <Amount value={1299} currencyDisplay="symbol" /> {/* $12.99 */}
3  <Amount value={1299} currencyDisplay="code" /> {/* USD 12.99 */}
4  <Amount value={1299} currencyDisplay="name" /> {/* 12.99 US dollars */}
5</Flex>

hideCurrency

Render only the formatted number, without any currency symbol, code, or name. Locale-driven separators and decimal places are preserved.

1<Flex gap={4}>
2  <Amount value={1299} hideCurrency /> {/* 12.99 */}
3  <Amount value={1299} currency="JPY" hideCurrency /> {/* 1,299 */}
4  <Amount value={1299} hideCurrency currencyDisplay="code" />
5  {/* 12.99 — currencyDisplay is ignored */}
6</Flex>

groupDigits

1<Flex gap={4}>
2  <Amount value={123456789} groupDigits /> {/* $1,234,567.89 */}
3  <Amount value={123456789} groupDigits={false} /> {/* $1234567.89 */}
4</Flex>

Large Numbers

For numbers larger than JavaScript's safe integer limit (2^53 - 1), pass the value as a string (supports decimals) or a bigint (integer-only). BigInt values are always treated as already in major units, so valueInMinorUnits is ignored for them.

1<Flex direction="column" gap={4}>
2  {/* 
3    For large numbers, use string (supports decimals) or bigint (integer-only)
4    to maintain precision 
5  */}
6  <Amount value="999999999999999" /> {/* $9,999,999,999,999.99 */}
7  <Amount value="10000100091636935" valueInMinorUnits={false} hideDecimals />
8  {/* $10,000,100,091,636,935 */}
9  {/* 
10    BigInt is always treated as major units — valueInMinorUnits is ignored 
11  */}
12  <Amount value={BigInt("9999999999999999999")} valueInMinorUnits={false} />
13  {/* $9,999,999,999,999,999,999.00 */}
14  {/* 
15    Numbers exceeding safe integer limit will show warning in console

With Text

1<Flex gap={4}>
2  <Text>
3    Total: <Amount value={1299} />
4  </Text>
5  <Text>
6    Discount: <Amount value={-299} />
7  </Text>
8  <Text>
9    Tax: <Amount value={199} />
10  </Text>
11</Flex>

Accessibility

  • Uses semantic HTML elements for proper content structure
  • Supports aria-label for providing accessible descriptions to screen readers