MoneyText

When to use

Wherever an amount of money is shown: a table cell, a summary card, a confirmation screen.

When not to use

• To enter an amount: Use AmountInput.
• For numbers that are not money: Intl.NumberFormat or StatCard is enough for counts and percentages.

Amounts in minor units

The amount always travels in the smallest unit (cents) as a bigint or an integer string: 123456n means 1.234,56 ₺. A floating-point number is never accepted, so there is no rounding error. The number of fraction digits comes from the currency: 2 for TRY, 0 for JPY.

Anatomy

₺1,234.56₺1,234.56TRY 1,234.56€1,234.56

LightDark

Copy code

import { MoneyText, Provider } from '@bigbang/ui';

export default function Default() {
  return (
    <Provider locale="en-GB">
      <div className="flex flex-col items-start gap-md">
        <MoneyText amount={123456n} size="lg" />
        <MoneyText amount="123456" />
        <MoneyText amount={123456n} display="code" />
        <MoneyText amount={123456n} currency="EUR" />
      </div>
    </Provider>
  );
}

1. Sign: Minus always; plus only with tone="sign" or signDisplay.
2. Integer part: Grouped by language (a point in Turkish).
3. Fraction: The decimal separator and the minor units; smaller with fraction="subtle".
4. Currency: At the end in Turkish, by the locale pattern in English.

Behaviour

• The format comes from Intl.NumberFormat fed the exact decimal string of the amount; even 20-digit amounts do not drift.
• When the amount changes, the new value rises in from below.
• The root is <data value="1234.56">, so the machine-readable value is in the page too.
• hidden replaces the amount with “••••” and the currency; the amount is then nowhere in the page (text, title, aria-*, data-*, the <data> value) and screen readers hear “Amount hidden”. The show and hide toggle is app state.
• compact writes short notation (“€1.2m”); only for charts and summaries, never for an amount the user acts on.

Guidelines

• Align amounts to the end in tables; tabular-nums keeps digits the same width.
• Do not change the currency position within a screen; use the default.
• Do not rely on colour alone; tone="sign" writes the sign too.

Content

Key	TR	EN
ui.money.currency-position	end	locale
ui.money-text.hidden	Tutar gizli	Amount hidden

Related components

• AmountInput: Amount entry.
• StatCard: Summary figures.