Number

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

overflow.number(options: CustomNumberElementOptions): CustomNumberElement

Example

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

`NumberAdornment`

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

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

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

Get started

Elements

Options

Events

Theming

Guides

Factory

Example

Options

`NumberAdornment`

Mode and precision

Range checks

Value

Inside Checkout

See also

​Factory

​Example

​Options

​NumberAdornment

​Mode and precision

​Range checks

​Value

​Inside Checkout

​See also

Factory

Example

Options

`NumberAdornment`

Mode and precision

Range checks

Value

Inside Checkout

See also