Amount

Formats and displays monetary values with the correct currency symbol, separators, and decimal places for a given locale.

Anatomy

Import and assemble the component:

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

3<Amount />

Usage

Amount takes a number and a currency and handles the formatting. The props below change what that formatting produces.

Basic

Pass a value and a currency code. Amount formats it for the active locale using Intl.NumberFormat, and renders in tabular numbers so columns of figures line up.

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

currency takes any ISO 4217 code. The symbol, its position, and the decimal and grouping separators all follow the currency and locale rather than being hard-coded.

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>

Currency display

How the currency is written: symbol (the default, $), code (USD), or name (US dollars).

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>

Number without currency

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>

Minor units

Set valueInMinorUnits when your API returns integer cents, paise, or fils. Amount divides by the currency's own exponent — 100 for USD, 1 for JPY — so you never hard-code the divisor.

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

Locale

locale overrides the browser locale for one value. Useful when an invoice must render in the customer's locale rather than the viewer's.

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>

Whole units

hideDecimals rounds to whole units. Use it in dense tables and summary figures where the fraction adds noise rather than precision.

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

Digit grouping

Thousands separators are on by default. Set groupDigits={false} for identifiers and reference numbers, where grouping would misread as a quantity.

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")} />
13  {/* $9,999,999,999,999,999,999.00 */}
14  {/* 
15    Numbers exceeding safe integer limit will show warning in console

With Text

Amount renders a span, so it composes inside Text and inherits size, weight, and color from it.

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>

API Reference

Formats and displays monetary values with locale and currency support.

Prop

Type

Slots

Every rendered part carries a stable data-slot attribute for styling and testing:

SlotElement
amountThe root <span> element

Accessibility

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