# Amount

Formats a number as money or a token amount.

[View source and API](https://github.com/tempoxyz/ds/blob/main/src/web/components/Amount.tsx)

## Overview

Formats a number in `en-US` with tabular figures, as money or followed by a token symbol.

## Examples

### Basic

```tsx
import { Amount } from '@tempoxyz/ds'

export function Demo() {
  return <Amount symbol="PathUSD" value="1250.50" />
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Basic.tsx)

### Size

Set `size` to `sm` (default), `md`, `lg`, or `xl`.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      {(['sm', 'md', 'lg', 'xl'] as const).map((size) => (
        <Amount key={size} size={size} symbol="PathUSD" value={1250.5} />
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Size.tsx)

### Currency

Set `currency` to an ISO 4217 code for money, or `symbol` to follow the number with a token symbol. Pass one, not both.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount currency="USD" size="lg" value={1234.5} />
      <Amount currency="EUR" value={1234.5} />
      <Amount size="lg" symbol="PathUSD" value={1234.5} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Currency.tsx)

### Align

Set `align` to `left` (default), `center`, or `right`.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      {(['left', 'center', 'right'] as const).map((align) => (
        <Amount align={align} currency="USD" key={align} size="md" value={1234.5} />
      ))}
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Align.tsx)

### Sign

Set `sign` to `+`, `-`, or `−` to prefix the amount.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount align="center" sign="+" size="md" symbol="PathUSD" value="1250.50" />
      <Amount align="right" currency="USD" sign="−" size="md" value={1234.5} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Sign.tsx)

### Strikethrough

Set `strikethrough` to mark a superseded amount.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount size="md" strikethrough symbol="PathUSD" value={1250.5} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Strikethrough.tsx)

### Precise

Set `precise` to show two significant digits for a currency value below the smallest shown unit.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount currency="USD" value={0.0004} />
      <Amount currency="USD" precise value={0.0004} />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Precise.tsx)

### Max Decimals

Set `maxDecimals` to cap the fraction digits shown.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount symbol="PathUSD" value="1.23456" />
      <Amount maxDecimals={2} symbol="PathUSD" value="1.23456" />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/MaxDecimals.tsx)

### Locale

Set `locale` to a BCP 47 tag, such as `de-DE`, to change grouping, decimal marks, and currency symbols. It defaults to `en-US`, so server and browser render the same text.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount currency="USD" value="1250.50" />
      <Amount currency="USD" locale="de-DE" value="1250.50" />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Locale.tsx)

### Masked

Set `masked` to show six dots in place of the amount, such as while people hide their balances. The value stays out of the page, so nobody can read, select, or copy it.

```tsx
import { Amount, style } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount currency="USD" size="lg" value="2097.75" />
      <Amount currency="USD" masked size="lg" value="2097.75" />
      <Amount masked symbol="PathUSD" value="1240.50" />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '12', maxWidth: '24rem !custom' })
}
```

[View example source](https://github.com/tempoxyz/ds/blob/main/docs/src/examples/demos/Amount/Masked.tsx)

## Anatomy

Import the component and assemble its parts.

```tsx
import { Amount } from '@tempoxyz/ds'

<Amount />
```

## Guidelines

### When to Use

* Show balances, payment amounts, fees, and converted values, such as 1,250.50 USDC or $1,250.50.
* Show amounts in tables, rows, and review screens with consistent formatting.

### When Not to Use

* Use [AmountInput](/docs/components/amount-input) when people enter an amount.
* Use `Table.Cell` with `numeric` in a [Table](/docs/components/table) for counts and metrics without a unit, such as TPS or block height.

### Always Show the Unit

**Do:** Pass `symbol` for a token amount and `currency` for money.

```tsx
/**
 * Do example for "Always Show the Unit" on the Amount page.
 * Pass `symbol` for a token amount and `currency` for money.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount size="md" symbol="USDC" value="1250.50" />
      <Amount currency="USD" value="1250.50" />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '4' })
}
```

**Don't:** Show an amount without its token or currency.

```tsx
/**
 * Don't example for "Always Show the Unit" on the Amount page.
 * Don't show an amount without its token or currency.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.stack()}>
      <Amount size="md" value="1250.50" />
      <Amount value="1250.50" />
    </div>
  )
}

namespace styles {
  export const stack = style({ display: 'grid', gap: '4' })
}
```

### Choose Currency or Symbol

* **Currency:** Money and converted values, such as a portfolio total.
* **Symbol:** Token amounts, such as what an account holds or sends.

Show a stablecoin balance in its token, such as PathUSD, even if it tracks the dollar. If you have a rate, add a converted value with `currency` as a second line.

### Pass Exact Decimal Strings

Pass `value` as a decimal string, such as a token balance converted from base units. Without `currency`, a string keeps its own fraction digits, including trailing zeros.

**Do:** Pass decimal strings, such as `"0.30"`.

```tsx
/**
 * Do example for "Pass Exact Decimal Strings" on the Amount page.
 * Pass decimal strings, such as `"0.30"`.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Available balance</span>
        <Amount align="right" symbol="USDC" value="1250.10" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Total fees</span>
        <Amount align="right" symbol="USDC" value="0.30" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

**Don't:** Pass numbers. They drop trailing zeros and show floating-point errors.

```tsx
/**
 * Don't example for "Pass Exact Decimal Strings" on the Amount page.
 * Don't pass numbers. They drop trailing zeros and show floating-point errors.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Available balance</span>
        <Amount align="right" symbol="USDC" value={1250.1} />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Total fees</span>
        <Amount align="right" symbol="USDC" value={0.1 + 0.2} />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

### Set Decimals by Purpose

* **With `currency`:** Shows the currency's own digits, two for USD. `maxDecimals={0}` renders `$5`.
* **Without `currency`:** Shows every digit of the string. Set `maxDecimals` in lists, and show the exact value in details and review screens.
* **Rounding:** `0.999` with `maxDecimals={2}` renders `1.00`. Show the exact balance wherever people choose how much to send.

**Do:** Use one decimal count down a column so decimal points line up.

```tsx
/**
 * Do example for "Set Decimals by Purpose" on the Amount page.
 * Use one decimal count down a column so decimal points line up.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Main wallet</span>
        <Amount align="right" symbol="USDC" value="1250.50" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Savings</span>
        <Amount align="right" symbol="USDC" value="84.10" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Payroll</span>
        <Amount align="right" symbol="USDC" value="312.00" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

**Don't:** Mix decimal counts in one column.

```tsx
/**
 * Don't example for "Set Decimals by Purpose" on the Amount page.
 * Don't mix decimal counts in one column.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Main wallet</span>
        <Amount align="right" symbol="USDC" value="1250.504812" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Savings</span>
        <Amount align="right" symbol="USDC" value="84.1" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Payroll</span>
        <Amount align="right" symbol="USDC" value="312.0005" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

### Show Values Below a Cent Precisely

A currency value below its smallest unit renders as a bound, such as `<$0.01`.

**Do:** Set `precise` on network fees to show two significant digits.

```tsx
/**
 * Do example for "Show Values Below a Cent Precisely" on the Amount page.
 * Set `precise` on network fees to show two significant digits.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>You send</span>
        <Amount align="right" symbol="USDC" value="250.00" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Network fee</span>
        <Amount align="right" currency="USD" precise value="0.0004" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

**Don't:** Show a fee people pay as a bound.

```tsx
/**
 * Don't example for "Show Values Below a Cent Precisely" on the Amount page.
 * Don't show a fee people pay as a bound.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>You send</span>
        <Amount align="right" symbol="USDC" value="250.00" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Network fee</span>
        <Amount align="right" currency="USD" value="0.0004" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

### Show Direction With a Sign

Set `sign="+"` for money in and `sign="−"` for money out. Pass `value` without its own minus, or the amount shows two signs. Prefer the minus sign `−` to the hyphen `-`.

**Do:** Mark incoming and outgoing amounts with `+` and `−`.

```tsx
/**
 * Do example for "Show Direction With a Sign" on the Amount page.
 * Mark incoming and outgoing amounts with `+` and `−`.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Received from Jane</span>
        <Amount align="right" sign="+" symbol="USDC" value="120.00" />
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Sent to 0x91bd…07e1</span>
        <Amount align="right" sign="−" symbol="USDC" value="48.50" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

**Don't:** Show direction with green and red alone.

```tsx
/**
 * Don't example for "Show Direction With a Sign" on the Amount page.
 * Don't show direction with green and red alone.
 * @module
 */
import { style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.list()}>
      <div {...styles.row()}>
        <span {...styles.label()}>Received from Jane</span>
        <span {...styles.credit()}>120.00 USDC</span>
      </div>
      <div {...styles.row()}>
        <span {...styles.label()}>Sent to 0x91bd…07e1</span>
        <span {...styles.debit()}>48.50 USDC</span>
      </div>
    </div>
  )
}

namespace styles {
  export const credit = style({
    color: 'content.positive',
    fontVariantNumeric: 'tabular-nums !custom',
    typography: 'body.b2Strong',
  })

  export const debit = style({
    color: 'content.negative',
    fontVariantNumeric: 'tabular-nums !custom',
    typography: 'body.b2Strong',
  })

  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const list = style({ display: 'grid', gap: '12', width: '100% !custom' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
  })
}
```

### Mark Superseded Amounts in Words

Use `strikethrough` for an amount that no longer applies, such as an expired fee quote, and show the new amount beside it.

**Do:** Say it in text, such as Was $0.02.

```tsx
/**
 * Do example for "Mark Superseded Amounts in Words" on the Amount page.
 * Say it in text, such as Was $0.02.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.label()}>Network fee</span>
      <div {...styles.values()}>
        <span {...styles.label()}>Was</span>
        <Amount currency="USD" strikethrough value="0.02" />
        <Amount currency="USD" value="0.01" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
    width: '100% !custom',
  })

  export const values = style({ alignItems: 'baseline', display: 'flex', gap: '8' })
}
```

**Don't:** Rely on the line. Screen readers don't announce it.

```tsx
/**
 * Don't example for "Mark Superseded Amounts in Words" on the Amount page.
 * Don't rely on the line. Screen readers don't announce it.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.label()}>Network fee</span>
      <div {...styles.values()}>
        <Amount currency="USD" strikethrough value="0.02" />
        <Amount currency="USD" value="0.01" />
      </div>
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
    width: '100% !custom',
  })

  export const values = style({ alignItems: 'baseline', display: 'flex', gap: '8' })
}
```

### Mask the Value, Not Its Look

Set `masked` on every amount while balances are hidden, including totals and converted values. Every masked amount shows the same six dots, which reveal neither its size nor its unit.

**Do:** Set `masked`, which renders the mask in place of the value.

```tsx
/**
 * Do example for "Mask the Value, Not Its Look" on the Amount page.
 * Set `masked`, which renders a fixed mask in place of the value.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.label()}>Balance</span>
      <Amount masked size="md" symbol="PathUSD" value="1240.50" />
    </div>
  )
}

namespace styles {
  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
    width: '100% !custom',
  })
}
```

**Don't:** Blur the amount. People can still select and copy it.

```tsx
/**
 * Don't example for "Mask the Value, Not Its Look" on the Amount page.
 * Don't blur the amount. The value stays in the page, where people can select and copy it.
 * @module
 */
import { Amount, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <div {...styles.row()}>
      <span {...styles.label()}>Balance</span>
      <Amount {...styles.blurred()} size="md" symbol="PathUSD" value="1240.50" />
    </div>
  )
}

namespace styles {
  export const blurred = style({ filter: 'blur(6px) !custom' })

  export const label = style({ color: 'content.secondary', typography: 'body.b2' })

  export const row = style({
    alignItems: 'baseline',
    display: 'flex',
    gap: '16',
    justifyContent: 'space-between',
    width: '100% !custom',
  })
}
```

### Size by Importance

* **Small (sm):** The default, for lists, tables, and rows.
* **Medium (md):** Card values and review totals.
* **Large (lg):** A balance at the top of a page.
* **Extra Large (xl):** The single balance on a home screen.

Amount renders as a block and ignores the alignment of a table cell. Set `align="right"` in an end-aligned column.

## Content

* Label each amount by its role, such as You send, Network fee, or Available balance.
* Don't repeat the unit in text, such as USD after $1,250.50.
* Don't abbreviate amounts people act on, such as 1.2K.
* Keep the label of a masked amount, such as Available balance, so people know what it hides.

## Accessibility

Renders a `<span>` with no role. Screen readers read the formatted text as written, or Hidden for a masked amount. How they read symbols, such as `$`, `−`, or the `<` in `<$0.01`, depends on the screen reader and its settings.

### Semantics

* **Root (span):** Plain text. Screen readers read the number with its sign and unit.
* **Locale (locale):** Formats in `en-US`. Set `locale` to the page language for other separators.
* **Strikethrough (strikethrough):** Visual only. Say in text that an amount is superseded.
* **Masked (masked):** Reads Hidden instead of the dots. The value is absent from the page.

### Your Responsibilities

* **Mark Inexact Amounts:** Say in text if an amount is a bound or estimate, such as "Less than $0.01".
* **Announce Live Updates (aria-live):** Amount does not announce updates. Put awaited ones, such as a quote, in a live region.
* **Label Direction in Words:** Keep the sign, and label direction in words, such as "Received" and "Sent".

## Related

[AmountInput](/docs/components/amount-input)

Use for entering amounts.

[TokenLogo](/docs/components/token-logo)

Use for the token icon beside an amount.

[Table](/docs/components/table)

Use for laying out amounts.

[ListGroup](/docs/components/list-group)

Use for laying out amounts.

[Payments](/docs/patterns/payments)

Covers send and review screens.

[Blockchain Values](/docs/patterns/blockchain-values)

Covers token amounts and fees.
