> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overflow.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Number

> A numeric input for merchant-defined quantities, amounts, or rates.

The `number` custom element renders a numeric input with optional prefix/suffix adornments, decimal precision, and range checks. Use it for merchant-defined quantities, monetary amounts, or rates.

## Factory

```typescript theme={null}
overflow.number(options: CustomNumberElementOptions): CustomNumberElement
```

## Example

```javascript theme={null}
const tip = overflow.number({
  name: 'tipAmount',
  label: 'Tip amount',
  mode: 'decimal',
  precision: 2,
  min: 0,
  prefix: { adornment: 'inset', label: '$' },
  suffix: { adornment: 'tab', label: 'USD' },
});

tip.on('onChange', ({ value, complete }) => console.log(value, complete));
tip.mount('#tip');
```

## Options

| Key                                                                 | Type                                        | Default                                                      | Notes                                                       |
| ------------------------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------- |
| `elementType`                                                       | `'number'`                                  | required                                                     | Discriminant when configured inside Checkout.               |
| `name`                                                              | `string`                                    | required                                                     | Unique per `Overflow` instance.                             |
| `label`                                                             | `string`                                    | required                                                     | Renders as `<label>`.                                       |
| `placeholder`                                                       | `string`                                    | none                                                         |                                                             |
| `defaultValue`                                                      | `number`                                    | `null`                                                       | Seeds the input on mount. Truncated to `precision`.         |
| `mode`                                                              | `'integer' \| 'decimal'`                    | `'decimal'`                                                  | Restricts the accepted character set.                       |
| `precision`                                                         | `number`                                    | none                                                         | Decimal-place cap. `mode: 'decimal'` only.                  |
| `min`                                                               | `number`                                    | none                                                         | Rejects values below this on submit.                        |
| `max`                                                               | `number`                                    | none                                                         | Rejects values above this on submit.                        |
| `prefix`                                                            | `NumberAdornment`                           | none                                                         | Renders on the leading edge.                                |
| `suffix`                                                            | `NumberAdornment`                           | none                                                         | Renders on the trailing edge.                               |
| `required`                                                          | `boolean`                                   | `false`                                                      | Empty input rejected by the built-in check.                 |
| `validate`                                                          | `(value: number \| null) => string \| null` | none                                                         | Overrides the built-in `required`, `min`, and `max` checks. |
| `disabled`, `readOnly`, `id`, `ariaLabel`, `locale`, `autocomplete` | shared                                      | see [reference](/payment-elements/elements/custom/reference) |                                                             |

### `NumberAdornment`

```typescript theme={null}
type NumberAdornment = {
  adornment: 'inset' | 'tab';
  label: string;
  ariaLabel?: string;
};
```

* `'inset'` overlays the adornment inside the input chrome. Best for short symbols (`$`, `%`).
* `'tab'` renders the adornment as a separate chip glued to one edge of the input. Best for short text labels (`USD`, `kg`).

Each side chooses its style independently. Adornments are non-interactive; clicks anywhere in the field focus the input.

### Mode and precision

* `mode: 'integer'` allows digits and a leading `-` only.
* `mode: 'decimal'` allows digits, a single `.`, and a leading `-`.
* `precision` caps how many decimal places the input accepts. Characters past the cap are blocked while typing. A `defaultValue` whose decimal part exceeds the cap is truncated on the right at mount.
* `precision` does not pad with trailing zeros. Values type-check as `number`, so the emitted value is exactly what shoppers see.

### Range checks

`min` and `max` run when `validate` is not supplied. Empty inputs (`null` after parse) skip the range check; the `required` check owns emptiness. Providing `validate` skips every built-in check.

## Value

```typescript theme={null}
type CustomNumberValue = number | null;
```

`null` while the input is empty or mid-typing an incomplete number (`'-'`, `'.'`, `'-.'`, `'1.'`). The next keystroke that resolves to a finite number flips `value` back to the parsed shape.

For arbitrary-precision arithmetic (currency rounding beyond four decimals), read `element.value` for the raw display string and apply your own decimal library downstream.

## Inside Checkout

```javascript theme={null}
overflow.checkout({
  paymentMethods: ['card'],
  customElements: {
    tipAmount: {
      elementType: 'number',
      label: 'Tip amount',
      prefix: { adornment: 'inset', label: '$' },
      precision: 2,
    },
  },
});
```

## See also

* [Custom elements introduction](/payment-elements/elements/custom/introduction)
* [Custom reference](/payment-elements/elements/custom/reference)
* [Validate option](/payment-elements/options/validate)