Component reference
CurrencyInput
Enter a budget with locale-aware currency formatting.
Preview
Live previewOptional six-digit hex. Clear to restore the preset. Check contrast with your brand color.
Changes apply to this preview only.
Campaign budget
The currency field clamps on blur, while Form validates the business rule on submit.
Width adapts to the available space
"use client";
import { useState } from "react";
import {
useForm,
Card,
CardHeader,
CardTitle,
CardDescription,
CardContent,
Form,
CurrencyInput,
FormError,
FormSubmit
} from "@pimolu/react";
interface BudgetValues {
budget: number | null;
}
function BudgetForm() {
const [saved, setSaved] = useState(false);
const form = useForm<BudgetValues>({
defaultValues: { budget: 2500 },
validate: (values) => {
if(values.budget === null) {
return { budget: "Enter a monthly budget." };
}
if(values.budget < 500) {
return {
budget: "The minimum monthly budget is $500.",
};
}
return undefined;
},
onSubmit: async () => {
await new Promise((resolve) => setTimeout(resolve, 600));
setSaved(true);
},
});
return (
<Card>
<CardHeader>
<CardTitle>Campaign budget</CardTitle>
<CardDescription>
The currency field clamps on blur, while Form validates the
business rule on submit.
</CardDescription>
</CardHeader>
<CardContent>
<Form form={form} className="grid gap-5 min-w-0">
<CurrencyInput
label="Monthly budget"
currency="USD"
locale="en-US"
min={0}
max={50000}
value={form.values.budget}
onValueChange={(value) => form.setValue(
"budget",
value
)}
invalid={Boolean(form.errors.budget)}
aria-describedby={form.errors.budget
? `${form.formId}-budget-error`
: undefined}
helperText="Between $0 and $50,000."
required
fullWidth
/>
<FormError name="budget" />
<FormSubmit>Save budget</FormSubmit>
{
saved && form.values.budget !== null && (<p role="status">
Budget saved: {
form.values.budget.toLocaleString(
"en-US",
{
style: "currency",
currency: "USD",
}
)
}
.
</p>)
}
</Form>
</CardContent>
</Card>
);
}
export function DemoExample() {
return (<BudgetForm />);
}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.
Sizes
sm, md and lg match the other text controls.
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.
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| Name | Type | Default | Description |
|---|---|---|---|
value | number | null | undefined | — | Controlled numeric value. `null` represents an empty field. The displayed text is formatted with `Intl.NumberFormat`. |
defaultValue | number | 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. |
currency | string | undefined | "USD" | ISO 4217 currency code. Defaults to "USD". |
locale | string | undefined | "en-US" | BCP 47 locale. Defaults to "en-US". |
decimals | number | undefined | 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 | — | Smallest allowed value, applied on blur. |
max | number | undefined | — | Largest allowed value, applied on blur. |
allowNegative | boolean | undefined | false | Accept a leading minus sign. Defaults to false. |
label | ReactNode | — | Visible label, associated with the text input. |
helperText | ReactNode | — | Supporting text below the field. |
errorMessage | ReactNode | — | Error text, replacing the helper text. |
invalid | boolean | undefined | false | Invalid state without an error message. |
size | PimoluCurrencyInputSize | undefined | "md" | Visual size. Defaults to "md". |
fullWidth | boolean | undefined | false | Stretch to the parent width. |
containerClassName | string | undefined | — | Class applied to the outer field. |
className | string | undefined | — | Standard React/HTML attribute. |
style | CSSProperties | undefined | — | Standard React/HTML attribute. |
aria-label | string | undefined | — | Defines a string value that labels the current element. |
children | ReactNode | — | Standard React/HTML attribute. |
onClick | MouseEventHandler<HTMLInputElement> | undefined | — | Standard React/HTML attribute. |
disabled | boolean | undefined | false | Standard React/HTML attribute. |
name | string | undefined | — | Standard React/HTML attribute. |
required | boolean | undefined | false | Standard React/HTML attribute. |
valuenumber | null | undefinedNo default extracted.
Controlled numeric value. `null` represents an empty field. The displayed text is formatted with `Intl.NumberFormat`.
defaultValuenumber | null | undefinedNo default extracted.
Initial numeric value when uncontrolled.
onValueChange((value: number | null) => void) | undefinedNo default extracted.
Called with the next number, or `null` when the field is empty.
currencystring | undefinedDefault: "USD"
ISO 4217 currency code. Defaults to "USD".
localestring | undefinedDefault: "en-US"
BCP 47 locale. Defaults to "en-US".
decimalsnumber | undefinedDefault: 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, ...).
minnumber | undefinedNo default extracted.
Smallest allowed value, applied on blur.
maxnumber | undefinedNo default extracted.
Largest allowed value, applied on blur.
allowNegativeboolean | undefinedDefault: false
Accept a leading minus sign. Defaults to false.
labelReactNodeNo default extracted.
Visible label, associated with the text input.
helperTextReactNodeNo default extracted.
Supporting text below the field.
errorMessageReactNodeNo default extracted.
Error text, replacing the helper text.
invalidboolean | undefinedDefault: false
Invalid state without an error message.
sizePimoluCurrencyInputSize | undefinedDefault: "md"
Visual size. Defaults to "md".
fullWidthboolean | undefinedDefault: false
Stretch to the parent width.
containerClassNamestring | undefinedNo default extracted.
Class applied to the outer field.
classNamestring | undefinedNo default extracted.
Standard React/HTML attribute.
styleCSSProperties | undefinedNo default extracted.
Standard React/HTML attribute.
aria-labelstring | undefinedNo default extracted.
Defines a string value that labels the current element.
childrenReactNodeNo default extracted.
Standard React/HTML attribute.
onClickMouseEventHandler<HTMLInputElement> | undefinedNo default extracted.
Standard React/HTML attribute.
disabledboolean | undefinedDefault: false
Standard React/HTML attribute.
namestring | undefinedNo default extracted.
Standard React/HTML attribute.
requiredboolean | undefinedDefault: false
Standard React/HTML attribute.
Accessibility
- Name the currency/amount and preserve typed editing and validation feedback.