# Amount

Formats a number as money or a token amount in your locale.

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

## Overview

Amount formats a number in the reader's locale with tabular figures, either as money or followed by a token symbol.

Pass amounts as decimal strings to avoid floating-point rounding.

## 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`, `md`, `lg`, or `xl`. It defaults to `sm`.

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

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: '3', 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 to format money, or `symbol` to follow the number with a token symbol. The two are mutually exclusive.

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

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: '3', 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`, `center`, or `right`. It defaults to `left`.

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

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: '3', 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 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: '3', 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. It defaults to `false`.

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

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: '3', 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 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: '3', 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 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: '3', maxWidth: '24rem !custom' })
}
```

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

## Guidelines

TODO: Write guidelines for Amount.