The CurrencyInput component is part of the @jutro/components package. It is mandatory to provide the availableCurrencies property (an array), with at least one element. If only one option is provided, the currency selection will not be editable and it will display that option.
You can also use the currencyDisplay property to determine whether to display the currency symbol ($, €, £...) or the code (USD, EUR, GBP...).
If you need to set an initial value, the initiaValue property can receive an object with 2 attributes: amount and currency.
As in the previous example, you need to set the availableCurrencies property with the list of currencies (using the currency code) available for selection:
The onChange event takes the new value you enter as its second parameter and uses it for the validation. If you want to display an error, use the stateMessages property:
import{ useCallback, useState }from'react'; import{CurrencyInput}from'@jutro/components'; exportfunctionCurrencyInputValidation(){ const[validationMessages, setValidationMessages]=useState({}); const onChange =useCallback((e, newValue)=>{ const componentValue = newValue.amount; if(!componentValue || componentValue !=10){ setValidationMessages({ error:["The value must be 10. If it's not, we won't not accept it."], }); }else{ setValidationMessages({}); } },[]); return( <CurrencyInput availableCurrencies={['USD']} label="Accept only 10" secondaryLabel="Will raise an error except when value is 10" stateMessages={validationMessages} onChange={onChange} /> ); }
You can use the value property for the controlled component scenario:
import{ useState }from'react'; import{CurrencyInput,NumberInput}from'@jutro/components'; exportfunctionCurrencyInputControlled(){ const[updatedValue, setAmount]=useState({ amount:200, currency:'USD', }); constonChange=(e, newValue)=>{ setAmount({amount: newValue,currency:'USD'}); }; return( <div> <NumberInput label="Enter the amount to be assigned to the next field" onChange={onChange} /> <CurrencyInput availableCurrencies={['USD']} label="Changes with the above" secondaryLabel="This value is automatically updated when the value in the first field changes" value={updatedValue} /> </div> ); }
Accessing ref property to set focus (Imperative Handler)
The currency input and other inputs, all allow the use of a ref property to access some native behaviors. However, only certain features are exposed. In this example, when you click the button, the focus will automatically be set in the currency input below.
import{ useRef }from'react'; import{CurrencyInput,Button}from'@jutro/components'; exportfunctionCurrencyInputRef(){ const currencyRef =useRef(null); constsetFocus=(e)=>{ currencyRef?.current?.focus(); }; return( <div> <Button label="Set focus on currency input" onClick={setFocus}></Button> <CurrencyInput availableCurrencies={['USD']} label="Get the focus from the button" ref={currencyRef} /> </div> ); }
Note: There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.
Helper text (optional): Provides extra context, hints, or helpful information to aid the user. Often used to explain specific requirements for correctly filling out a field.
Currency code or symbol: specifies and displays the currency type, helping users accurately enter and understand monetary values.
Currency input field: the container, consisting of a fill and a stroke, in which the user enters data.
Use help text to provide guidance about what to input and how. Here are some examples of what you might include in help text:
Context to aid the user, such as how the information will be used
Hints for what kind of information goes inside the input field
Formatting examples or requirements
Only use help text for pertinent information. Avoid using help text that simply restates the same information that appears in the label.
Use sentence case for help text. Write the help text as 1-2 short, complete sentences that end with a period. When showing formatting examples, you don't need to end with a period.
Do use help text to provide additional aid or context to the user.
Don't use help text to simply restate the same information that appears in the label.
Don't put placeholder text in the currency entry field. Placeholder text strains users' short-term memory because it disappears once a value is entered. It also poses additional burdens for users with visual and cognitive impairments.
Instead, place hints and instructions, including formatting examples and requirements, outside of the field.
Error message text tells a user how to fix the error. In the case of the currency input field, errors are often related to something that must be fixed for in-line validation. For example, in a claims submission process, if the user doesn't fill out a required field for estimated repair cost, you could use error text to guide them to a solution: “Enter the estimated cost of repairs.”
Use sentence case for error text. Write 1-2 short, complete sentences that end with a period.
Do use error text to guide the user and show them a solution.
Don't write ambiguous error messages or leave users guessing as to how to resolve a problem.
Use an asterisk (*) to indicate required fields. The asterisk precedes the field label. This helps users to easily locate which fields are required by scanning just the left-most character of the label.
In addition to marking required fields with an asterisk, it is recommended to include clear instructions at the top of the form, such as "All fields marked with an asterisk are mandatory," to ensure users understand the meaning of the asterisk.
Do use an asterisk to indicate that a field is required.
Don't use an asterisk to denote anything that is optional.
The currency input field appears with no value (default), placeholder text, or a filled input.
Visual
State
Description
No value (default)
Indicates to the user that no value has been entered and there is no placeholder.
Placeholder
Indicates to the user that no value has been entered. The placeholder is grayed out.
Filled input
Indicates to the user that the input is filled with data.
Currency input fields also have interactive states for enabled, focus, disabled, error, read-only, and display-only.
State
Description
Enabled
Indicates to the user that the element is enabled for interaction.
Focus
Indicates to the user which UI element in the system is focused.
Disabled
Indicates to the user that the input value can't be changed because of local factors. For example, a checkbox above the input field must be checked to access this input field. The user can take action to enable it by interacting with the page.
Error
Indicates that the user has made a validation error. Error text provides corrective feedback to users.
Read-only
Indicates to the user that the input value can't be changed because of outside factors. For example, lack of write access. The user can take action to enable it by, for example, contacting an administrator.
Display-only
The display-only state is used for two cases:
A UI element is used in display mode.
A UI element is displayed in edit mode, but is never editable.
The input field is associated with its label through a 'for/id' relationship. Checking the 'required' knob in Storybook toggles the aria-required value from 'true' to 'false'.
The thousands separator doesn't display while the user is entering data. It appears after the input is complete and the user has clicked or tabbed away from the field.
The contrast ratio of textual elements against their background is above 4.5:1 as per WCAG 2.1 AA requirements. Non-textual content that needs to convey meaning (such as icons and keyboard focus visibility) has a contrast ratio of at least 3:1 with its adjacent colors. All content is visible and functional up to and including 400% without requiring scrolling in two dimensions.
This component has been validated to meet the WCAG 2.1 AA accessibility guidelines. However, changes made by the content author can affect accessibility conformance.
When using this component within your application, be sure to check the following:
The labels and instructions are meaningful and concise. Provide supplemental instructions if necessary.
The component displays the correct currency (the default is USD).
If the input field is required, check the aria-required checkbox in Storybook.
Note: There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.
Make sure to understand the Design System components API surface, and the implications and trade-offs. Learn more in our introduction to the component API.
If set to true, displays the component value in plain text. Consider using readonly instead, if possible, because plain text is worse for accessibility than readonly inputs.
The ISO Currency Code for this value's currency. Must be an element of the ISO Currency code array.
Description
Value of input. Takes precedence over initialValue. If this prop is passed, component works in controlled mode and its value will change only if this prop changes.
The result of passing the id and max properties is that they will be part of the HTML input that is created in the HTML DOM. In the case of max, it will prevent the user from writing any value above 10 (it can only be done by directly pasting the value).
Jutro inputs have implemented imperative handlers as a mechanism to provide access to some common native features that might be useful for you. The following features are available:
Set focus to allow you to set the user focus into a specific component
Blur to remove the focus from the component
Scroll to the component so that you can take the user to a specific area of the page.
These features are provided through the ref property, which exposes them as follows:
This is controlled by the availableCurrencies property. If you provide more than 1 currency code, the component displays a dropdown to allow selection. This does not apply when displayOnly or readOnly props are set to true.
If the initialValue or value properties are assigned with a currency code that is not included in the availableCurrencies property, the component render fails.
Invalid currency code in 'initialValue.currency', 'availableCurrencies' does not contain: GBP
If the initialValue or value props don't specify the currency to be selected by default, the component will use the first currency passed in the availableCurrencies property as default.
Although some Jutro components might provide complementary features or a helper function to facilitate the validation process, it is your responsibility as a developer to handle the validation of any user input (using or not using the complementary helpers) and to decide what error messages to show.
Jutro components behave based on the developer implementation.
When are error messages displayed?
Error messages are only displayed when you pass them to the component through the stateMessages property. This property receives an object with the following content:
The component displays every error message provided in the same order as in the array.
When does validation occur?
This is your decision as a developer. As components do not determine when the validation is performed or when the error must be displayed, you need to implement the logic to handle it according to the project requirements, for example while the user is editing the content, when the component loses focus, and on form submission.
New @jutro/components/CurrencyInput component introduced that replaces CurrencyField.
The previous CurrencyField component was deprecated and moved to the @jutro/legacy package. To view its documentation, switch to a version of the documentation older than 10.0.
