Currency input

Currency input 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.

Usage

Overview

A currency field is an enhanced input field that enables users to enter an amount of money in a specified currency.

When to use

When you need users to input money in a specific currency, such as euros and dollars.

When not to use

When you need to input a numeric value and incrementally increase or decrease the value, use the number input instead.

Formatting

Anatomy

1. Label: describes the purpose of an input field.
2. 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.
3. Currency code or symbol: specifies and displays the currency type, helping users accurately enter and understand monetary values.
4. Currency input field: the container, consisting of a fill and a stroke, in which the user enters data.

Label position

The label for the currency input field can appear at the top (default and recommended) or on the left of the input itself.

Currency codes and symbols

Currency codes follow the ISO 4217 standard. When setting up the component, you can change from currency code to symbol (for example, USD to $).

For multiple currencies, currency codes or symbols appear in a closed list and are ordered alphabetically.

Content

General writing guidelines

• Use sentence case for all aspects of designing Guidewire product interfaces. Don't use title case.
• Use present tense verbs and active voice in most situations.
• Use common contractions to lend your copy a more natural and informal tone.
• Use plain language. Avoid unnecessary jargon and complex language.
• Keep words and sentences short.

Include a label

Place a clear, visible label outside the currency input field. An input field without a label is ambiguous and not accessible.

Do position a permanent label outside the field.

Don't assume that the field is self-explanatory without a label.

Use help text

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 use placeholder text

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.

Source: Nielsen Norman Group

Do place hints and instructions, including formatting examples and requirements, outside of the field.

Don't add placeholders to the currency entry field.

Use error text to guide users

Error message text tells a user how to fix the error. For currency input fields, errors are often related to validation issues that must be fixed. For example, in a claims submission process where a user doesn't fill out a required field for estimated repair cost, you could use error text like "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.

Mark required fields

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.

Use sentence case

Field labels appear in sentence case.

Refer to the UI text style guide for more information on how to implement sentence case.

Do use sentence case.

Don't use title case. It hinders readability.

Behaviors

States

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. This state was called “read-only” before.

Interactions

Mouse

Users can activate a currency input by clicking in the area inside the border.

Keyboard

The input element is keyboard accessible. Users can navigate into and out of the component using the TAB key.

Screenreader

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'.

Thousands separator

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.

Accessibility

This component has been validated to meet the WCAG 2.2 AA accessibility guidelines in its default, base configuration. This includes ensuring:

• The contrast ratio of textual elements against their background is above 4.5:1.
• Non-textual content that needs to convey meaning (like icons and focus indicators) has a contrast ratio of at least 3:1 with its adjacent colors.
• The item is operable using a keyboard, as well as using a mouse.
• Content is accessible using screen readers, such as JAWS and VoiceOver.

Accessibility conformance ultimately depends on how this component is implemented and customized. Changes made by the content author can affect accessibility. For details on our shared responsibility model, please review our full Jutro accessibility statement.

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.

Code

<CurrencyInput
  availableCurrencies={['USD', 'EUR']}
  label="Currency input component"
/>;

Import statement

import { CurrencyInput } from '@jutro/components';

Component contract

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.

Properties

availableCurrenciesrequired

Type

ISOCurrencyCodes

Description

List of ISO 4217 currency codes. At least one currency needs to be defined in an array The first currency will be used as a default one.

labelrequired

Type

IntlMessageShape

Description

Label associated with input field, also passed as a default value to aria-label.

className

Type

string

Description

CSS class name for this component.

currencyDisplay

Type

'code' | 'symbol'

Description

Whether the currency will be displayed as a symbol or as text.

Default value

'symbol'

decimalPlaces

Type

number

Description

The number of decimal places to display in the value. If it is set, the user is prevented from entering too many digits after the decimal point. If the value or initialValue props have too many digits after the decimal point, the displayed figure is rounded to the closest valid value.

Default value

2

disabled

Type

boolean

Description

If set to true, component is rendered in disabled state.

displayOnly

Type

boolean

Description

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.

hideGrouping

Type

boolean

Description

If set to true, it will hide intl currency value formatting on currency input.

hideLabel

Type

boolean

Description

If set to true, the label is not visible.

initialValue

Type

{ amount: number, currency: ISOCurrencyCode }

amount

Type

number

Description

The number to display.

currency

Type

ISOCurrencyCode

Description

The ISO Currency Code for this value's currency. Must be an element of the ISO Currency code array.

Description

Initial value of input. If value prop is specified along with this prop, this prop's value is discarded. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.

labelPosition

Type

'top' | 'left'

Description

Allows to select label position.

Default value

'top'

onChange

Type

function (React.ChangeEvent<HTMLInputElement>, {amount: number, currency: ISOCurrencyCode})

amount

Type

number

Description

The number to display.

currency

Type

ISOCurrencyCode

Description

The ISO Currency Code for this value's currency. Must be an element of the ISO Currency code array.

Description

Callback invoked when component value is changed.

placeholder

Type

IntlMessageShape

Description

Placeholder to display on an empty component.

readOnly

Type

boolean

Description

If set to true, component is rendered in a read-only state. For values in plain text, consider using displayOnly.

required

Type

boolean

Description

If set to true, component is rendered as required and label has asterisk.

secondaryLabel

Type

IntlMessageShape

Description

Secondary label text to display.

stateMessages

Type

{ error: string[] }

Description

An object with a list of error messages for the current state.

tooltip

Type

{ text: intlMessageShape, trigger: string } | intlMessageShape

text

Type

IntlMessageShape

Description

Text to show tooltip content.

trigger

Type

string

Description

The trigger to show the tooltip.

Description

Text to be displayed in the tooltip or tooltip object that includes: text - to show tooltip content, trigger - to set tooltip trigger.

value

Type

{ amount: number, currency: ISOCurrencyCode }

amount

Type

number

Description

The number to display.

currency

Type

ISOCurrencyCode

Description

The ISO Currency Code for this value's currency. Must be an element of the ISO Currency code array.

Description

Value of the input. Takes precedence over initialValue. If this prop is passed, the component works in controlled mode and its value only changes if this prop changes. If the decimalPlaces prop is specified along with this prop, the displayed value is rounded to the closest valid value.

ISOCurrencyCodes and ISOCurrencyCode types

The ISOCurrencyCodes type is a string array of ISO 4217 currency codes.

The ISOCurrencyCode type is a string with a value of any element in the ISOCurrencyCodes array.

  [
'AED',
'AFN',
'ALL',
'AMD',
'ANG',
'AOA',
'ARS',
'AUD',
'AWG',
'AZN',
'BAM',
'BBD',
'BDT',
'BGN',
'BHD',
'BIF',
'BMD',
'BND',
'BOB',
'BOV',
'BRL',
'BSD',
'BTN',
'BWP',
'BYN',
'BZD',
'CAD',
'CDF',
'CHE',
'CHF',
'CHW',
'CLF',
'CLP',
'CNY',
'COP',
'COU',
'CRC',
'CUC',
'CUP',
'CVE',
'CZK',
'DJF',
'DKK',
'DOP',
'DZD',
'EGP',
'ERN',
'ETB',
'EUR',
'FJD',
'FKP',
'GBP',
'GEL',
'GHS',
'GIP',
'GMD',
'GNF',
'GTQ',
'GYD',
'HKD',
'HNL',
'HTG',
'HUF',
'IDR',
'ILS',
'INR',
'IQD',
'IRR',
'ISK',
'JMD',
'JOD',
'JPY',
'KES',
'KGS',
'KHR',
'KMF',
'KPW',
'KRW',
'KWD',
'KYD',
'KZT',
'LAK',
'LBP',
'LKR',
'LRD',
'LSL',
'LYD',
'MAD',
'MDL',
'MGA',
'MKD',
'MMK',
'MNT',
'MOP',
'MRU',
'MUR',
'MVR',
'MWK',
'MXN',
'MXV',
'MYR',
'MZN',
'NAD',
'NGN',
'NIO',
'NOK',
'NPR',
'NZD',
'OMR',
'PAB',
'PEN',
'PGK',
'PHP',
'PKR',
'PLN',
'PYG',
'QAR',
'RON',
'RSD',
'RUB',
'RWF',
'SAR',
'SBD',
'SCR',
'SDG',
'SEK',
'SGD',
'SHP',
'SLE',
'SLL',
'SOS',
'SRD',
'SSP',
'STN',
'SVC',
'SYP',
'SZL',
'THB',
'TJS',
'TMT',
'TND',
'TOP',
'TRY',
'TTD',
'TWD',
'TZS',
'UAH',
'UGX',
'USD',
'USN',
'UYI',
'UYU',
'UYW',
'UZS',
'VED',
'VES',
'VND',
'VUV',
'WST',
'XAF',
'XAG',
'XAU',
'XBA',
'XBB',
'XBC',
'XBD',
'XCD',
'XDR',
'XOF',
'XPD',
'XPF',
'XPT',
'XSU',
'XTS',
'XUA',
'XXX',
'YER',
'ZAR',
'ZMW',
'ZWL',
]

Hooks

No hooks are available for CurrencyInput.

Translation keys

There are only 2 translation keys associated to the CurrencyInput component, both related to the aria-label default text:

Key	Used for
jutro-components.fields.CurrencyDisplay.ariaLabel	aria-label value for the currencies dropdown
jutro-components.fields.CurrencyInput.ariaLabel	aria-label value for the field description

Escape hatches

For more information, see our documentation about escape hatches.

The following options are available:

• Design Tokens
• className property
• Passing native HTML attributes
• Ref with imperative handlers
• Native event property

Passing HTML properties to the component

You can use HTML input attributes, except for those which are overridden by Jutro. These attributes will be assigned to the amount input element.

<CurrencyInput
  availableCurrencies={['USD', 'EUR']}
  initialValue={{
    amount: 5,
    currency: 'USD',
  }}
  label="Currency input component"
  id="amountID1"
  max={10}
/>

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).

Ref with imperative handlers

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:

    const componentRef = useRef(null);

    const setFocus = () => {
        componentRef?.current.focus();
    }

    const removeFocus = () => {
        componentRef?.current.blur();
    }

    const scrollToComponent = () => {
        componentRef?.current.scrollIntoView();
    }

    <Component ref={componentRef}>

More options might be included in the future.

CurrencyInput custom behaviors

CurrencyInput has some custom behaviors implemented as part of the component:

Single vs Multiple currencies

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.

Invalid values handling

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

Default currency assignment

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.

Controlled currency input limitations

You can use React states to control the value of a CurrencyInput, but there are some limitations when doing so.

1. The onChange event is only triggered if the input is focused. If the value is updated as a controlled component, the onChange callback does not run.
2. If the CurrencyInput has a decimalPlaces property and receives a value from a React state update, the displayed value is rounded to the closest valid value.

For example, in the code below you can use the first input to change the value of the second input. You can observe the following two behaviors when doing so:

1. If a value bigger than 100 or less than 0 is entered in the first input, the validation messages do not show in the second input because its callback does not run.
2. If any decimal values are entered, the value displayed in the second input is rounded to the closest integer.

export function CurrencyInputDecimalPlacesControlledExample() {
  const [firstInputValue, setFirstInputValue] = useState({
    amount: 200,
    currency: 'USD',
  });
  const [validationMessages, setValidationMessages] = useState({});
  const max = 100;
  const min = 0;

  const handleFirstInputChange = useCallback((event, newValue) => {
    console.log(newValue);
    if (newValue && newValue.amount !== undefined && newValue.currency) {
      setFirstInputValue(newValue);
    }
  }, []);

  const handleSecondInputChange = useCallback(
    (event, newValue) => {
      setValidationMessages({});

      if (
        newValue &&
        newValue.amount !== undefined &&
        (newValue.amount > max || newValue.amount < min)
      ) {
        setValidationMessages({
          error: ['Value must be between 0 and 100'],
        });
      }
    },
    [max, min]
  );

  return (
    <CurrencyInput
      label="First currency input"
      secondaryLabel="Change this value to see the second input update"
      onChange={handleFirstInputChange}
      availableCurrencies={['USD']}
    />
    <CurrencyInput
      label="Second currency input"
      secondaryLabel="Value controlled by the first input"
      value={firstInputValue}
      decimalPlaces={0}
      onChange={handleSecondInputChange}
      availableCurrencies={['USD']}
      stateMessages={validationMessages}
      min={min}
      max={max}
    />
  );
}

Disabled, displayOnly and readOnly precedence

If two or more of the properties disabled, displayOnly, and readOnly are set to true at the same time, the precedence is as follows:

displayOnly > readOnly > disabled

User input validation

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:

{
  error: ['error message 1', 'error message 2', 'error message N'];
}

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.

Legacy information

Are you using the legacy CurrencyField component?

• To view docs for the old components, switch to a version of the documentation older than 10.0.
• These legacy components are also available in Storybook: CurrencyField

Note: There are deprecated versions of this component. Switch to a version of the docs older than 10.0.x to view their docs.

Examples

Check out the Usage section for details about how and when to use the CurrencyInput component.

Basic currency input example

The CurrencyInput component is part of the @jutro/components package. It is used to render an input for currency values. It is mandatory to provide an array of ISO 4217 currency codes to the availableCurrencies property to list the currencies a user can select.

<CurrencyInput
  availableCurrencies={['USD', 'EUR']}
  label="Currency input component"
/>;

Currency input with only one currency available

If only one currency option is provided, the currency selection is not editable and it displays that option.

<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
/>;

Currency input with an initial value

To add an initial value to a CurrencyInput, you need to give both an amount and a currency.

<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
  initialValue={{
    amount: 15467,
    currency: 'USD',
  }}
/>;

Currency code display options

You can set a CurrencyInput to display either a currency symbol or the ISO 4217 currency code.

<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
  initialValue={{
    amount: 15467,
    currency: 'USD',
  }}
  currencyDisplay='code'
/>
<CurrencyInput
  availableCurrencies={['USD']}
  label="Currency input component"
  initialValue={{
    amount: 15467,
    currency: 'USD',
  }}
  currencyDisplay='symbol'
/>

Decimal places

The decimalPlaces property specifies the number of decimal places to display. It limits users from entering too many digits after the decimal point, but if the initialValue or value properties are set, the number is rounded to the nearest valid value.

For example, if decimalPlaces is set to 0 the user cannot enter any digits. However, the initialValue or value properties can have decimal digits.

<CurrencyInput
  label="Currency input component limited decimals"
  placeholder="Enter a value"
  secondaryLabel="Try to add an additional decimal"
  decimalPlaces={0}
  availableCurrencies={['USD']}
/>
<CurrencyInput
  label="Currency input with initial value"
  secondaryLabel="Rounded up from 5.66"
  initialValue={{currency: 'USD', amount: 5.66}}
  decimalPlaces={0}
  availableCurrencies={['USD']}
/>
<CurrencyInput
  label="Currency input with value"
  secondaryLabel="Rounded up from 5.66"
  value={{currency: 'USD', amount: 5.66}}
  decimalPlaces={0}
  availableCurrencies={['USD']}
/>

User input validation on change

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';

export function CurrencyInputValidation() {
  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}
    />
  );
}

Controlled component

You can use the value property for the controlled component scenario:

import { useState } from 'react';
import { CurrencyInput, NumberInput } from '@jutro/components';

export function CurrencyInputControlled() {
  const [updatedValue, setAmount] = useState({
    amount: 200,
    currency: 'USD',
  });

  const onChange = (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';

export function CurrencyInputRef() {
  const currencyRef = useRef(null);

  const setFocus = (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>
  );
}

Changelog

10.13.0

A new property decimalPlaces was added to the CurrencyInput component. It is set to 2 by default and the user is prevented from entering additional digits past the decimalPlaces limit.

The initialValue or value properties can have extra digits after the decimal point, but the value displayed is rounded to the nearest valid value.

10.0.0

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.

Original component location:

• CurrencyField: @jutro/components/CurrencyField

Updated component location:

• CurrencyField: @jutro/legacy/components/CurrencyField

Codemods are available to automatically rename existing imports.