Text input

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

Examples

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

Basic input

The TextInput component only needs the label property to be displayed. Other props like placeholder, secondaryLabel, and onChange can be used to complement its behavior.

<TextInput
  label="Text input component"
  placeholder="Write what you want here"
  secondaryLabel="Free text input"
/>

Display only

TextInput along with the other inputs, all provide the option of setting the component as display only. When this property displayOnly is set to true, the component is displayed as text, without the specific input look and feel.

<TextInput
  label="Text input component"
  placeholder="Write what you want here"
  secondaryLabel="Free text input"
  value="this is the value"
  displayOnly={true}
/>

Tooltip

The tooltip property will make the component display the tooltip icon. When the user interacts with it, it also displays some complementary information. This property can receive text to be displayed {text: "this will be displayed when tooltip is opened"}. You can also control what specific action makes the tooltip appear by passing a second attribute trigger. This accepts the standard HTML events like pointerover, focus, and blur. By default, the tooltip is opened by clicking on the tooltip icon.

In this example, the tooltip is displayed when the mouse is over the tooltip icon.

<TextInput
  label="Text input component"
  placeholder="Write what you want here"
  secondaryLabel="Free text input"
  tooltip={{ text: 'tooltip text', trigger: 'pointerover' }}
/>

Text input validation on change

TextInput does not provide specific validation logic but it provides a method for including developer validation and uses the stateMessages property to display any required error message.

This is an example of handling validation when the onChange event is triggered.

function TextInputValidation() {
  const [validationMessages, setValidationMessages] = useState({});

  const onChange = useCallback((e, newValue) => {
    if (!newValue || newValue.indexOf('a') == -1) {
      setValidationMessages({});
    } else {
      setValidationMessages({
        error: ['The text cannot contain `a` character'],
      });
    }
  }, []);

  return (
    <TextInput
      label="Do not accept words with 'a'"
      secondaryLabel="Will raise an error if contains 'a' character"
      stateMessages={validationMessages}
      onChange={onChange}
    />
  );
}

Controlled component

The value property can be used for the controlled component scenario:

export function InputControlled() {
  const [updatedValue, setNewValue] = useState('first given value');

  const onChange = (e, newValue) => {
    setNewValue(newValue);
  };

  return (
    <div>
      <TextInput
        label="Enter here the value to be assigned input below"
        onChange={onChange}
      />
      <br />
      <TextInput
        label="Changes with the above"
        secondaryLabel="This cannot be manually modified"
        value={updatedValue}
      />
    </div>
  );
}

Using ref to set focus

TextInput along with other inputs, all allow the use of a ref property to access some native behaviors. However only some features are exposed. In this case, when the button is clicked, the focus is automatically set in the following input:

export function InputRef() {
  const inputRef = useRef(null);

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

  return (
    <div>
      <Button
        label="Set focus on text input"
        onClick={setFocus}></Button>
      <TextInput
        label="Get the focus from the button"
        ref={inputRef}
      />
    </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.

Usage

Overview

The text input component enables users to enter text and numbers into data-entry fields. Text inputs are among the most important and most used interface components that users interact with. They allow users to provide the necessary information that a system requires to fulfill a specified task or set of tasks.

When to use

• To enter unique information that can't be predicted with a predefined set of options.
• For single-line text entry.

When not to use

• For date or time entry. Use the date picker and time picker components instead.
• When the user needs to search for something. Use the lookup component instead.
• If the user can only enter an option from a predefined list. Consider using a selection control such as the dropdown or radio group.

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. Text input field: the text field container, consisting of a fill and a stroke, where users input text.

Label position

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

Text input sizing and width

The size of the input should be proportional to the amount of text that you want the user to provide.

Source: Nielsen Norman Group

Do match fields to the type and size of the input.

Don't use excessively long input fields.

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 text 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 text 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 text entry fields.

Use error text to guide users

Error message text tells a user how to fix the error. In the case of the text input field, errors are often related to something that must be fixed for in-line validation. For example, if the user doesn't fill out a required field that asks for their email address, you can use error text to guide them to a solution: “Enter your email address.”

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

Text 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 text input by clicking in the area inside border.

Keyboard

The text input component is keyboard focusable.

Screenreader

The label and input are programmatically associated with each other. By default, a tooltip is positioned beside the label. It includes the WAI-ARIA attribute of aria-label="Show tooltip", and also aria-expanded="false" which toggles to "true" when the tooltip is triggered. Content within the tooltip is voiced by screen readers by means of the WAI-ARIA role of 'alert'. When the required checkbox is checked in Storybook, the attribute of 'required' is added to the markup and the aria-required value toggles from 'true' to 'false'.

Text overflow

If content inside the text input overflows, the user should be able to scroll horizontally from one end to the other by using Shift+Scroll. The user can also use Left Arrow and Right Arrow keys to move the cursor from one side to the other.

Accessibility

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, ensure that labels and instructions are meaningful and concise. Provide supplemental instructions if necessary.

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

<TextInput label="Text input component" />

Import statement

import { TextInput } 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

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.

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.

hideLabel

Type

boolean

Description

If set to true, the label is not visible.

initialValue

Type

string

Description

Initial value of input. If value prop is specified along with this prop, this prop's value is discarded.

labelPosition

Type

'top' | 'left'

Description

Allows to select label position.

Default value

'top'

onChange

Type

function (React.ChangeEvent<HTMLInputElement>, string)

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

string

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.

Hooks

No hooks are available for TextInput.

Translation keys

There are no translations for TextInput.

For information on how to manage translations, see our section about Internationalization.

Escape Hatches

For more information, see our documentation about escape hatches.

The following options are available:

• Design tokens
• A className property
• The ability to pass native HTML attributes
• Ref with imperative handlers
• A native event property

Passing HTML properties to the component

You can use HTML input attributes, except any that are overridden by Jutro. These attributes are assigned to the HTML input element.

<TextInput
  label="Text input component"
  id="textID1"
  maxLength={10}
/>

The result of passing these id and maxLength properties is that they will be part of the HTML input that is created in the HTML DOM. In the case of maxLength, it prevents the user from writing more than 10 characters. This 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.

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 InputField 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

Changelog

10.0.0

New @jutro/components/TextInput component introduced that replaces InputField.

The previous InputField 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.

Component	Old location	New location
InputField	@jutro/components/InputField	@jutro/legacy/components/InputField

Codemods are available to automatically rename existing imports.