# CurrencyField component for Stripe Apps Use CurrencyField to create a currency input field. # v8 > This is a v8 for when app-sdk-version is 8. View the full page at https://docs.stripe.com/stripe-apps/components/currencyfield?app-sdk-version=8. The `CurrencyField` component isn’t available in the selected SDK version. # v9 > This is a v9 for when app-sdk-version is 9. View the full page at https://docs.stripe.com/stripe-apps/components/currencyfield?app-sdk-version=9. To add the `CurrencyField` component to your app: ```js import {CurrencyField} from '@stripe/ui-extension-sdk/ui'; ``` `CurrencyField` is an input field for accepting an amount of a specified currency. Amounts are formatted according to the currency’s specifications. > The value returned by CurrencyField is a positive integer representing the monetary amount in the smallest currency unit. For example, $10.00 is 1000 in USD (or any other two-decimal currency) and ¥100 is 100 in JPY (a zero-decimal currency). ## Props ### CurrencyField props | Property | Type | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `autoFocus` | (Optional) `boolean | undefined` If `true`, React focuses the element on mount. | | `currency` | (Optional) `Currency | undefined` The currency that the value is denominated in. | | `currencyAllowlist` | (Optional) `Currency[] | undefined` The list of selectable currencies. | | `defaultCurrency` | (Optional) `Currency | undefined` The currency the component should start with. This allows initial control if the component is going to be uncontrolled. | | `defaultValue` | (Optional) `number | undefined` The value the component should start with. This allows initial control if the component is going to be uncontrolled. | | `description` | (Optional) `string | undefined` Descriptive text that’s rendered adjacent to the control’s label. | | `disabled` | (Optional) `boolean | undefined` Sets whether or not the element should be disabled. Prevents selection. | | `error` | (Optional) `string | undefined` Error text that’s rendered below the control. | | `fractionDigitOffset` | (Optional) `number | undefined` Override the allowed “sub-cent” accuracy. By default, we use the currency’s default number of fractional digits, for example, 2 for USD. This allows you to override that behavior, by providing a number of additional digits to allow. This is only used in rare cases, as it might have unintended localization consequences. You must make sure that the data source you’re integrating with expects this, since it often means that the we no longer provide a whole integer. You can also provide a negative value to reduce the default fractional accuracy. | | `hiddenElements` | (Optional) `("label" | "description" | "error")[] | undefined` Visually hides the specified elements. The hidden elements are still present and visible to screen readers. | | `label` | (Optional) `React.ReactNode | undefined` Text that describes the control. The control is both visible and clickable. | | `onChange` | (Optional) `((value: Amount) => void) | undefined` The callback function to fire when the value changes. | | `onCurrencyChange` | (Optional) `((currency: Currency) => void) | undefined` The callback function to run when the currency changes. | | `padAllFractionDigits` | (Optional) `boolean | undefined` If you use the fractionDigitOffset prop, by default, we only pad the fraction digits that are expected by default. In USD, this means padding 2 zeros. ($5 -> $5.00). This is means that users aren’t visually prompted to add more decimals if they don’t have them, but they’re allowed to add them. If padAllFractionDigits is true, we pad all the digits. (e.g. $5 -> $5.0000) | | `readOnly` | (Optional) `boolean | undefined` If `true`, the input is not editable by the user. | | `size` | (Optional) `("small" | "medium" | "large") | undefined` The size of the component. | | `value` | (Optional) `Amount | undefined` An integer representing the amount of the currency, denominated in that currency’s smallest unit. For example, $10.00 is 1000 in USD (or any other two-decimal currency) and ¥100 is 100 in JPY (a zero-decimal currency) | ## More examples ### Uncontrolled ### Allowed currencies By default, `CurrencyField` renders a currency selector containing all currencies. To narrow the list of currencies that appear in the currency selector down to a smaller subset, provide a list of currency codes to the `currencyAllowlist` prop. When an allowlist of 1 or fewer currencies is provided, the currency selector is omitted and the selected currency is defaulted to the allowed currency (or `USD` if the allowlist is empty). ### Disabled and read only You can mark a field as `disabled`, which prevents any interaction and changes the styling. Disabled means that no data from that form element is submitted when the form is submitted. You can also make a field as `readOnly`. Read-only means any data from within the element is submitted, but the user can’t change it. ### Size Changing the `size` allows you to choose variants with slightly more or slightly less room than the default. In general, don’t mix and match different sizes within the same form. The default is `medium`. ### Sub-cent precision Use `fractionDigitOffset` when you need more or fewer fractional digits than the currency’s default. It’s relative to each currency’s normal precision (not a fixed number of decimals for every currency), so behavior stays sensible across currencies. Positive values add fractional precision. Values can be decimals (for example `USD` still uses cents as the unit, but you might see values like `1234.56` meaning `12.3456`). Make sure your backend and any math you do can handle that, including floating-point caveats. Negative values reduce fractional digits only (for example to drop cents). You can’t use it to force multiples of whole units (like “only tens”). With `fractionDigitOffset`, optional `padAllFractionDigits` pads either only the default fraction length or every fractional digit implied by the offset. ## See also - [Design patterns to follow](https://docs.stripe.com/stripe-apps/patterns.md) - [Style your app](https://docs.stripe.com/stripe-apps/style.md) - [UI testing](https://docs.stripe.com/stripe-apps/ui-testing.md)