CurrencyInput

Anatomy

+----------------------+
| $   1,234.56    USD  |
+----------------------+

When to use

Any price / cost / amount input in checkout, invoicing, pricing forms.
Inputs that need to display currency-aware formatting (commas vs periods, symbol position).

Examples

Basic

<CurrencyInput defaultValue={1234.5} />

Localized

<CurrencyInput currency="EUR" locale="de-DE" defaultValue={1234.5} />
// → "1.234,50  €  EUR"

Allowing negatives (refunds / adjustments)

<CurrencyInput
  currency="USD"
  positiveOnly={false}
  defaultValue={-25}
/>

Inside a react-hook-form

const { setValue, watch } = useFormContext<{ price: number }>();

<CurrencyInput
  value={watch('price')}
  onValueChange={(v) => setValue('price', v ?? 0)}
  currency="USD"
/>

Tokens

See the tokens block in this spec’s frontmatter.

Install: @helixui/core

import { CurrencyInput } from '@helixui/core'

status: stable · since: 0.1.0

Tags: currency, money, money-input, locale, intl, payment, pricing

Props

Name	Type	Default	Description
`value`	`number \| null`	`undefined`	Controlled numeric value.
`defaultValue`	`number \| null`	`undefined`	Uncontrolled initial value.
`onValueChange`	`(value: number \| null) => void`	`undefined`	Fires with the parsed numeric value or null when the field is empty.
`currency`	`string`	`USD`	ISO 4217 currency code. Drives the symbol and the default precision.
`locale`	`string`	`navigator.language`	Override the user’s locale. Affects symbol position and decimal separator.
`showSymbol`	`boolean`	`true`	Render the currency symbol inside the input.
`precision`	`number`	`undefined`	Override the number of decimal places. Defaults to what the currency expects.
`positiveOnly`	`boolean`	`true`	Reject negative values.
`size`	`'sm' \| 'md' \| 'lg'`	`md`	Input size.
`tone`	`'brand' \| 'neutral' \| 'danger'`	`brand`	Tone for focus ring.

Tokens used

color.bg.input, color.bg.surface.default, color.bg.action.brand.subtle, color.border.subtle, color.border.action.brand, color.border.danger, color.text.primary, color.text.muted, radius.md, spacing.1, spacing.2, spacing.3, spacing.4, font.size.xs, font.size.sm, font.size.md, font.size.lg

Accessibility

Role: textbox

Keyboard

Key	Action
`0-9`	Enter digits.
`.`	Decimal separator (or `,` depending on locale).

Notes

Uses inputmode='decimal' so mobile keyboards show the numeric layout.
On blur the value reformats with thousands separators.
Without an explicit aria-label, defaults to e.g. “USD amount”.