Text Inputs

Intro

Text input controls are used to request text entries from users. They are usually found in create and edit patterns as part of completing the task.

Text input controls on mobile (left) and tablet (right)

Variations

Currently, there are two types of text inputs. Depending on the length of the text that users need to provide, the two types are:

Simple property form cell for single-line input
Note form cell for multi-line input

Simple Property Form Cell

A simple property form cell consists of a label (property key) and a text field (user input text). It is used for collecting short input. The label is required for the simple property form cell. It helps users to identify the purpose of the text entry.

Simple property form cell

Empty State: An optional placeholder text can be used to display a correct input value when the field is empty. It explicitly shows the user what is the expected text entry. Do not use placeholder text to give instructions since placeholder text will disappear once the user starts typing. Use helper text instead.

An optional helper text can be used to provide additional instructions. Helper text should be short and precise. Avoid wrapping to two lines.

Error State: When the user-entered value does not pass validation, the simple property form cell will enter an error state. An error icon appears, indicating that this cell has an error, and a message will appear below the text input to provide instructions on how to fix the error. Do NOT display both helper text and an error message at the same time. Replace the helper text with the error message when the field is in an error state.

Simple property form cell with helper text (top) and validation message (bottom)

Active Typing State: When the user is actively typing, a clear icon will appear at the right end of the text field. The user can tap the clear icon to delete all input. Generally, simple property form cells are used to collect short user inputs. The height of the field is fixed. The text will overflow to the left if the user types more than one line.

Overflow of text entry in a simple property form cell

Read-Only State: A simple property form cell in read-only state indicates the current user role does not have the authorization to edit this field while the information in the field is relevant to fulfill the task. The text field changes to a gray background to hint this is non-interactive, with a helper text below saying “Read-only field”. The user can select and copy the existing value text, but cannot activate the text field.

Disabled State: If a simple property form cell is disabled, the input in this field (if any) does not affect the task of the user. The disabled cell has an opacity of 50% to reduce distraction.

Simple property form cell in read only state (top) and disabled state (bottom)

Simple Property Form Cell with Scan

A secondary action can be added to a simple property form cell to provide input methods besides typing. Currently, the SDK supports getting a text value through bar code or QR code scan. A scan icon is used to indicate the feature. A helper text can be used to explain the feature to the user.

A scanner is launched when the user taps on the scan icon. The user may scan a barcode or QR code of an object to get the property specified in the cell. The value will be filled in the simple property cell. If needed, the user may edit the value directly.

Simple property form cell with scan

Scan QR code using simple property form cell with scan

Simple Property Form Cell with Show/Hide Password

For password entry, special secondary action is added to the simple property form cell. By default, password entry is displayed in an encrypted format. The user can tap on the eye icon to toggle password visibility.

Simple property form cell in read only state (top) and disabled state (bottom)

Note Form Cell

The note form cell is best used for collecting long user input, such as a note, comment, or description.

Note form cell

Empty State: The default state of the note form cell has a taller text field compared to the simple property form cell, which encourages the user to give a long input. An optional placeholder text can be used to show a sample correct input to the user. Placeholder text will disappear once the user starts typing. An optional helper text can be used to provide additional instructions which should be always visible to the user.

Error State: When the input does not pass validation, an error icon appears inside the text field and an error message appears below. The error message should tell the user clearly how to fix the error. Do NOT display both helper text and error message at the same time. Replace helper text with the error message when the field is in an error state.

Note form cell with helper text (top) and validation message (bottom)

Active Typing State: Initially, the note form cell text field can display three lines of text. As the user keeps typing, the text field can expand to a maximum height of six lines of text. This avoids the note form cell from covering the whole screen. After reaching the maximum height, the cell stops expanding. The content would scroll vertically inside the text field area as the text continues to wrap to a new line.

Overflow of text entry in a note form cell

Read-Only State: A note form cell in the read-only state means the current user role does not have the authorization to edit this field. The text field changes to a gray background to indicate this is non-interactive, with a helper text below saying “Read-only field”. When in read-only state, the text field can expand to exceed the maximum height so the text value is visible without scrolling inside the text field. The user can select and copy the existing text entry but cannot change the text in the field.

Disabled State: If a note form cell is disabled, the input in this field does not affect the task of the user. The disabled cell has an opacity of 50% to reduce distraction.