Skip to content
THE COMPONENT LIBRARY
Skip to content

Component reference

CurrencyInput

Enter a budget with locale-aware currency formatting.

Preview

Live preview

Changes apply to this preview only.

Campaign budget

The currency field clamps on blur, while Form validates the business rule on submit.

Between $0 and $50,000.

Width adapts to the available space

More examples

Different configurations and compositions using the real Pimolu API. Each preview runs independently and follows the site appearance.

Locales and currencies

The same value formats differently: symbol placement, grouping and fraction digits all come from Intl.

Open preview

Sizes

sm, md and lg match the other text controls.

Open preview

Controlled value, min and max

Focus the field to see the raw number; blur to format it. Values outside min/max are clamped on blur, and an empty field reports null.

Open preview

Usage

Keep numeric amounts, currency and locale explicit; do not treat a display string as financial arithmetic.

API reference

Generated from the public TypeScript declarations. Native HTML attributes are inherited where the component extends them; this reference includes Pimolu props and selected common native attributes.

PimoluCurrencyInputProps

Type source
PimoluCurrencyInputProps public API
NameTypeDefaultDescription
valuenumber | null | undefined—Controlled numeric value. `null` represents an empty field. The displayed text is formatted with `Intl.NumberFormat`.
defaultValuenumber | null | undefined—Initial numeric value when uncontrolled.
onValueChange((value: number | null) => void) | undefined—Called with the next number, or `null` when the field is empty.
currencystring | undefined"USD"ISO 4217 currency code. Defaults to "USD".
localestring | undefined"en-US"BCP 47 locale. Defaults to "en-US".
decimalsnumber | undefinedthe currency convention (2 for USD, 0 for JPY, ...)Fraction digits used for the final format. Defaults to the currency convention (2 for USD, 0 for JPY, ...).
minnumber | undefined—Smallest allowed value, applied on blur.
maxnumber | undefined—Largest allowed value, applied on blur.
allowNegativeboolean | undefinedfalseAccept a leading minus sign. Defaults to false.
labelReactNode—Visible label, associated with the text input.
helperTextReactNode—Supporting text below the field.
errorMessageReactNode—Error text, replacing the helper text.
invalidboolean | undefinedfalseInvalid state without an error message.
sizePimoluCurrencyInputSize | undefined"md"Visual size. Defaults to "md".
fullWidthboolean | undefinedfalseStretch to the parent width.
containerClassNamestring | undefined—Class applied to the outer field.
classNamestring | undefined—Standard React/HTML attribute.
styleCSSProperties | undefined—Standard React/HTML attribute.
aria-labelstring | undefined—Defines a string value that labels the current element.
childrenReactNode—Standard React/HTML attribute.
onClickMouseEventHandler<HTMLInputElement> | undefined—Standard React/HTML attribute.
disabledboolean | undefinedfalseStandard React/HTML attribute.
namestring | undefined—Standard React/HTML attribute.
requiredboolean | undefinedfalseStandard React/HTML attribute.
value

number | null | undefined

No default extracted.

Controlled numeric value. `null` represents an empty field. The displayed text is formatted with `Intl.NumberFormat`.

defaultValue

number | null | undefined

No default extracted.

Initial numeric value when uncontrolled.

onValueChange

((value: number | null) => void) | undefined

No default extracted.

Called with the next number, or `null` when the field is empty.

currency

string | undefined

Default: "USD"

ISO 4217 currency code. Defaults to "USD".

locale

string | undefined

Default: "en-US"

BCP 47 locale. Defaults to "en-US".

decimals

number | undefined

Default: the currency convention (2 for USD, 0 for JPY, ...)

Fraction digits used for the final format. Defaults to the currency convention (2 for USD, 0 for JPY, ...).

min

number | undefined

No default extracted.

Smallest allowed value, applied on blur.

max

number | undefined

No default extracted.

Largest allowed value, applied on blur.

allowNegative

boolean | undefined

Default: false

Accept a leading minus sign. Defaults to false.

label

ReactNode

No default extracted.

Visible label, associated with the text input.

helperText

ReactNode

No default extracted.

Supporting text below the field.

errorMessage

ReactNode

No default extracted.

Error text, replacing the helper text.

invalid

boolean | undefined

Default: false

Invalid state without an error message.

size

PimoluCurrencyInputSize | undefined

Default: "md"

Visual size. Defaults to "md".

fullWidth

boolean | undefined

Default: false

Stretch to the parent width.

containerClassName

string | undefined

No default extracted.

Class applied to the outer field.

className

string | undefined

No default extracted.

Standard React/HTML attribute.

style

CSSProperties | undefined

No default extracted.

Standard React/HTML attribute.

aria-label

string | undefined

No default extracted.

Defines a string value that labels the current element.

children

ReactNode

No default extracted.

Standard React/HTML attribute.

onClick

MouseEventHandler<HTMLInputElement> | undefined

No default extracted.

Standard React/HTML attribute.

disabled

boolean | undefined

Default: false

Standard React/HTML attribute.

name

string | undefined

No default extracted.

Standard React/HTML attribute.

required

boolean | undefined

Default: false

Standard React/HTML attribute.

Accessibility

  • Name the currency/amount and preserve typed editing and validation feedback.
Read the accessibility guide →