Back to Components

Input Fields

Overview

Form input fields provide a structured format for capturing form data, such as text, dates, emails and other data types. Further customization of input fields can be achieved by providing a custom input component, such as an application-specific control.

warning-icon
This component is in the process of being broken out and deprecated.
There will be breaking changes to the API. Proceed with caution.


Best Practices

Form fields should:

  • Be clearly labelled. When the field's purpose is clear from context, a label should be visually hidden to ensure the label is available for screen readers.
  • Validate input as soon as possible, usually when users have finished interacting with the field. For validation that may take some time to evaluate, defer validation until form submission.

Form fields should not:

  • Use custom z-indices. See more about layering in our theming guide.

Content guidelines

  • Use placeholder text with example input values where additional context is valuable
  • Provide helper text to assist with filling out a form field, or clarify the purpose of the information being captured. Form helper text should be succinct.
  • Provide short and concise error messages, explaining what went wrong and how to fix it.
  • Mark fields as optional where the information provided isn't essential for the purpose of the form. Don't mark required fields with asterisks.

Examples

Standard text field

Allows users to provide short text input. Optionally, additional context can be given in the form of helper text to provide further instructional content.

Code example
Playroom
Provide the name of your favorite Sesame Street character.

Field with validation error

Lets the user know that there is a problem with the provided input.

Whenever possible, validate the input after the user has finished their interaction with a field (but not before). If the user does not interact with the field before the form is submitted, the input should be validated on submission of the form. Error messages should be removed as early as possible, ideally as the user is typing, so that the user can see when an error has been addressed.

  • use the error prop to provide a validation message to display to the user. The presence of a value indicates that the field is currently in an invalid state.
  • use the touched prop to indicate that the user has interacted with or has visited the field. This value is used to determine whether or not to show an error and helps to avoid overwhelming users with error messages for fields they have not interacted with.

Note: Recipe doesn't maintain the value of touched, and instead expects the touched state to be managed within the application, typically via formik or another form validation library. For a complete example demonstrating these props in use, see the Cookbook: Complex form example.

Code example
Playroom
This is a hint about how this field works
First name is required
0/120

Long text field

Allows user to provide text input that may span more than one line. Optionally, a character count can be used to indicate the restrictions on the maximum length of an input. Use size to specify how tall the field should be with the options: small, medium, large.

Code example
Playroom
23/120

Numeric input field

Allows the user to provide numeric input values.

Code example
Playroom

Password input field

Allows the user to securely enter a password, typically as part of a login form.

Code example
Playroom

Email input field

Allows the user to input email values.

  • Can be paired with the any of the following props to forward supported HTML input element attributes onto the rendered input element: list, maxLength, minLength, multiple, pattern, placeholder, and readOnly.
Code example
Playroom

Select list

Allows the user to choose between a larger set of options than would be appropriate for radio buttons. Use type="select" to enable the user to pick from a dropdown list of available options.

  • Use type="select" to enable the user to pick from a list of available options.
  • Use options to provide a array of objects with label and value properties for each option to present for selection. Optionally add description if a label needs further detail.
  • Use onSelectionChange to identify the selected item. The onSelectionChange callback is provided the value of the selected option.

Using onChange for EzField[type=select] is currently supported, but is deprecated in favor of onSelectionChange.

Code example
Playroom

Select list with grouping

Allows the user to choose from smaller lists of logically related options. Use a select list grouping to make the list of options easier to navigate to assist the user in finding the option they are looking for. The group prop should be applied to each option that belongs to a group, and represents the label that wil be used to group the items.

Options are presented in the order in which they are grouped, and then by the order in which they are provided. To avoid options rendering options out of sequence, provide the options prop a list pre-sorted by group.

Code example
Playroom

Autosuggest list

Allows the user to filter longer lists of options to a set that match the text entered.

If you have fewer than 6 items, consider using radio buttons instead.

  • Use type="autosuggest" to enable the user to pick from a filtered list of available options.
  • Use onSelectionChange to identify the selected item.
  • Use onFilter to react to user text input, in order to filter options to match. When updating the options list, it is strongly recommended that results are first sorted so that options are listed in the order in which the term appears earliest. For example, when searching "al", "Albany, New York" appears before "Tallahassee, Florida".

When providing

Code example
Playroom

Date input field

Allows the user to pick a date from a popup calendar or enter their own date directly into the input field. Use type="date" to enable the user to pick a date from a popup calendar.

Dates in this component are displayed with the format MM/DD/YYYY.

Code example
Playroom
This is the date your food will be delivered.

Date input within range

Allows the user to pick a restricted range of available dates from a popup calendar or enter their own date directly into the input field.

While the minDate and maxDate options will prevent the selection of unavailable dates from the calendar, additional validation is required to prevent invalid values from being entered directly into the input.

  • Use type="date" to enable the user to pick a date from a popup calendar.
  • Use the optional minDate={dateValue} prop to disallow the selection of dates prior to dateValue.
  • Use the optional maxDate={dateValue} prop to disallow the selection of dates after dateValue.
Code example
Playroom
This is the date your food will be delivered.

Date input with filtered range

Allows the user to pick from an arbitrary selection available dates from a popup calendar or enter their own date directly into the input field.

While the filterDate option will prevent the selection of unavailable dates from the calendar, additional validation is required to prevent invalid values from being entered directly into the input.

  • Use type="date" to enable the user to pick a date from a popup calendar.
  • Use the optional filterDate={fn} prop to restrict the range of dates presented to only the set that are returned by the filter.

The below example demonstrates using the filterDate prop to restrict the calendar selection to only allow weekdays.

Code example
Playroom
This is the date your food will be delivered.

Date input field with programmatic clear

Programmatically clear the selection in a date input.

Code example
Playroom
This is the date your food will be delivered.

Time input field

Allows the user to pick a time from a select dropdown. Use type="time" to enable the user to pick a time from a select dropdown. An optional range can be used to limit the number of options in the select dropdown. Use start="9:00am" to specify the start of the range, and end="5:00pm" to specify the end of the range. An optional step can change the interval in which the times are generated. By default the step is 60 minutes. You can change it by adding step={15}.

The steps that are supported are: 5, 10, 15, 20, 30, 60

Optional Props:

  • displayAsNoon: <boolean>: Replaces the "12:00 PM" label with "Noon"
  • focusLabel: <string>: Determines which option is guaranteed to be within view when the dropdown opens

Times in this component are displayed with the format h:mma, for example, 9:45am.

Code example
Playroom
This is the time your food will be delivered.

Custom input field

Allows the usage of application-specific input components while still providing standard field behaviors, such as validation. The custom component will have props forwarded from EzField.

Code example
Playroom

Text field with hidden label

Visually hide the fields label when the fields purpose is clear from context.

  • Label text should still be provided to provide context for users of assistive technology.
Code example
Playroom
Search

Text field with small label

This is alternative style of label for fields, reserved for fields where the intent of the field is otherwise clear from the context of the page, such as filter controls inside the page header or subheader.

This label style should be used to provide additional context in an understated way, as not to draw the focus away from the primary actions on the page.

  • It is recommended that small labels are NOT used in conjunction with helperText.
Code example
Playroom

Text field with placeholder text

Provides the user with additional context hint about the expected input.

Code example
Playroom

Disabled text field

Show users that a field is not available for interaction. Often used where a form field is not available due to the current state of the form.

Code example
Playroom

Browser support

The Field component internally uses Array.prototype.findIndex() and may require a polyfill to provide browser support depending on the specific requirements for your application. We recommend using Polyfill.io in your application to apply necessary polyfills only when they are needed for the requesting browser.

Current theme

Theme

Contents