# AmountInput

Accepts a decimal amount, such as a payment or transfer value.

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

Figma: [Inputs/Amount Input](https://www.figma.com/design/yE96kcymnNR88PJp6G1sPs?node-id=5227-1389) (`AmountInput.Root`)

## Overview

An amount input is a filled card with the label, the amount in heading-size digits, a token chip, and the balance. It keeps the value as a raw string and rejects input that is not a non-negative decimal.

## Examples

### Basic

Place the `Field.Label`, a [Token](/docs/components/token), and a `Field.Description` inside `AmountInput.Root`. They take their own rows above and below the amount.

```tsx
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'

export const fill = true
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <AmountInput.Root>
        <Field.Label>You send</Field.Label>
        <AmountInput.Control placeholder="0.00" />
        <Token address="0x20c0000000000000000000000000000000000000" symbol="pathUSD" />
        <Field.Description>Balance 2,480.32</Field.Description>
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ maxWidth: '24rem !custom' })
}
```

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

## Anatomy

Import the component and assemble its parts.

```tsx
import { AmountInput, Token } from '@tempoxyz/ds'

<AmountInput.Root>
  <AmountInput.Control />
</AmountInput.Root>
```

## Guidelines

### When to Use

* Enter a money or token amount, such as for Send, Convert, or Add funds.
* Put it first in a dialog body, above the recipient field.

### When Not to Use

* Use [NumberField](/docs/components/number-field) for whole quantities adjusted in steps, such as webhook retries.
* Use [TextInput](/docs/components/text-input) for identifiers with digits, such as a 0x address or a bank account number.
* Use [OtpField](/docs/components/otp-field) for one-time verification codes.
* Use [Amount](/docs/components/amount) to show a read-only value, such as a balance or a network fee.

### Name the Token Beside the Digits

Put a [Token](/docs/components/token) after `AmountInput.Control`. Give it `readOnly` when the token is fixed, and pass it to a picker trigger's `render` when the token can change.

**Do:** Name the token beside the amount with a [Token](/docs/components/token).

```tsx
/**
 * Do example for "Name the Token Beside the Digits" on the AmountInput page.
 * Name the token beside the amount with a `Token`.
 * @module
 */
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <AmountInput.Root defaultValue="120.50">
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control placeholder="0.00" />
        <Token readOnly symbol="PathUSD" />
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

**Don't:** Leave the token to the page around the card.

```tsx
/**
 * Don't example for "Name the Token Beside the Digits" on the AmountInput page.
 * Don't leave the token to the page around the card.
 * @module
 */
import { AmountInput, Field, style } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <AmountInput.Root defaultValue="120.50">
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control placeholder="0.00" />
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

### Show the Available Balance

Put the spendable balance in a `Field.Description` inside the card, such as Balance: 250.00 USDC, with the decimals and token code used elsewhere in the product.

**Do:** Show the spendable balance in the card, below the amount.

```tsx
/**
 * Do example for "Show the Available Balance" on the AmountInput page.
 * Show the spendable balance in the card, below the amount.
 * @module
 */
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <AmountInput.Root>
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control placeholder="0.00" />
        <Token readOnly symbol="USDC" />
        <Field.Description>Balance: 250.00 USDC</Field.Description>
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

**Don't:** Leave the balance to another part of the page.

```tsx
/**
 * Don't example for "Show the Available Balance" on the AmountInput page.
 * Don't leave the balance to another part of the page.
 * @module
 */
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root {...styles.field()}>
      <AmountInput.Root>
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control placeholder="0.00" />
        <Token readOnly symbol="USDC" />
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

### Explain Invalid Amounts in Text

The root allows any number of fraction digits. Check the value against the token's decimals, such as 6 for USDC, and against the balance. Set `invalid` on the `Field.Root` and add a `Field.Error` that names the limit.

* **Separator:** A period or a lone comma separates decimals, so `1,5` is `1.5` and `0,250` is `0.250`. A lone comma groups thousands when one to three digits without a leading zero precede it and three follow it, as in `1,250`. Several commas group thousands. With both separators, the last one separates decimals, so `1.250,50` is `1250.50`.
* **Value:** Keep the raw string from `onValueChange`. Convert it with exact decimal math, not floating-point numbers.

**Do:** Name the limit in a `Field.Error`, such as the token's decimals.

```tsx
/**
 * Do example for "Explain Invalid Amounts in Text" on the AmountInput page.
 * Name the limit in a `Field.Error`, such as the token's decimals.
 * @module
 */
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <AmountInput.Root defaultValue="12.5000001" invalid>
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control />
        <Token readOnly symbol="USDC" />
        <Field.Error match>Enter an amount with up to 6 decimal places.</Field.Error>
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

**Don't:** Rely on the red fill alone.

```tsx
/**
 * Don't example for "Explain Invalid Amounts in Text" on the AmountInput page.
 * Don't rely on the red fill alone.
 * @module
 */
import { AmountInput, Field, style, Token } from '@tempoxyz/ds'

/** Renders the static preview, which the guideline card shows inert. */
export function Demo() {
  return (
    <Field.Root invalid {...styles.field()}>
      <AmountInput.Root defaultValue="12.5000001" invalid>
        <Field.Label>Amount</Field.Label>
        <AmountInput.Control />
        <Token readOnly symbol="USDC" />
      </AmountInput.Root>
    </Field.Root>
  )
}

namespace styles {
  export const field = style({ width: '100% !custom' })
}
```

### Stack Two Cards for a Conversion

For a conversion, place a From card and a To card one above the other, with a small arrow [Button](/docs/components/button) between them that swaps the two.

## Content

* **Label:** Use You send and You receive on a send or convert screen, and Amount in other forms.
* **Balance:** Write Balance and the amount, such as Balance 2,480.32.

## Accessibility

`AmountInput` renders a native text input for decimal amounts inside the card.

### Semantics

* **AmountInput.Control (textbox):** A text input with a decimal keypad. Name it with `Field.Label`, or `aria-label` if no label fits.
* **Animated Digits (aria-hidden):** Decorative. Screen readers read the value from the input, not from the morphing digits.
* **Invalid (aria-invalid):** Set `invalid` on the root, or on the `Field.Root`, to fill the card red and mark the input.
* **Reduced Motion (prefers-reduced-motion):** The digits stop morphing and change at once. The nudge on an invalid amount doesn't play.

### Keyboard

* **Move to the TextInput (Tab):** Moves focus to the input, then to the token chip when it is a button.
* **Ignore Other Keys (Letters):** Keystrokes that don't form a non-negative decimal leave the value unchanged.

The ignored keystrokes have no announcement. State the accepted format, such as the decimal limit, in the description.

### Your Responsibilities

* **Label the Field (Field.Label):** Give the field a visible label, and name the token in the chip or the description.
* **Explain Invalid Amounts (Field.Error):** Say what is allowed, such as "Enter up to 250.00 USDC", not only with the red fill.

## Related

[Amount](/docs/components/amount)

Use for displaying amounts.

[Field](/docs/components/field)

Use for the label, balance, and error.

[NumberField](/docs/components/number-field)

Use for stepped quantities.

[Token](/docs/components/token)

Use for the token pill beside the amount.

[Payments](/docs/patterns/payments)

Covers send, review, and confirmation flows.
