Skip to main content

Input

An input is a field that allows a user to enter and interact with text and numeric values.

BetaInput replaces the text type of input from v1.

Code documentation

Web

Anatomy

The input component is made up of 13 elements.

Anatomy diagram numbering 13 elements of an input.
  1. Label
  2. Optional indicator
  3. Right slot
  4. Counter
  5. Clear button
  6. Value
  7. Left slot
  8. Helper text
  9. Required indicator
  10. Current value length
  11. Max value length
  12. Counter divider
  13. Error text

Variants

Size

The size of the input can be adjusted to accommodate a variety of space constraints. These sizes use fixed dimensions to guarantee that the height doesn't grow based on the content of the input field. This ensures that all form elements of the same size compliment and predictably align with each other.

Small

Small inputs are used to reduce the overall height of the input field. They are recommended for forms with a high number of inputs or contexts that require more conservative vertical spacing.

An input includes a label and a field with sample value text. The field has top and bottom padding that is roughly equal to the line-height of the value.

Medium

Medium inputs are the default size.

An input includes a label and a field with sample value text. The field has top and bottom padding that is slightly taller than the line-height of the value.

Large

Large inputs are recommended for forms with a relatively limited number of inputs or to improve touch triggering.

An input includes a label and a field with sample value text. The field has top and bottom padding that is nearly twice the line-height of the value.

Label

Every input should have a label that describes the purpose of the input in a concise and clear manner. Built-in labels can be omitted if an adjacent label is included that adequately describes the purpose of the input and is correctly referenced to the field for accessibility purposes.

The top input displays a sample label immediately above an input field. The bottom input does not include a label.

Label text that is longer than the available space wraps to a new line.

The input label text wraps to a second line when it meets the edge of an implied container around the input.

Indicator

Inputs can be marked as either required or optional which triggers relevant validation on the form. The indicator is a preset and styled element within the component, not manually entered as part of the label string.

Required form elements are used when the majority of the form elements are optional, but a few need to be marked as required.

An input includes an indicator styled as a red asterisk to the right of the label.

Optional form elements are used when the majority of the form elements are required, but a few elements need to be marked as optional.

An input includes an indicator with the word optional in parentheses to the right of the label.

Helper text

Helper text is used to convey additional information about the input such as format requirements.

Sample helper text is displayed between the label and the input field.

Helper text wraps to a new line when it's too long for the available horizontal space.

The helper text of the input wraps to a second line when it meets the edge of an implied container around the input.

Left slot

A left slot is available for an icon to describe the type of input required, such as a date picker, or as a touch target to trigger nested components. When the slot is hidden, the input text expands to fill the available space.

A sample icon is displayed to the left of a sample value to indicate the position of a left slot.

When interactivity is required, a button should be used within the slot. This ensures the appropriate interactions are automatically enabled and affords a focus area for easy keyboard navigation. Consider using small, tertiary, icon-only buttons for consistency and to compliment the rest of the input elements.

The top input includes a sample icon-only button without a container. The bottom input includes a sample icon-only button with a container and a focus ring. Both buttons are left-aligned within the field to indicate the position of a left slot.

Value

Values that are longer than the input are handled using the behavior of native HTML inputs where the text is cropped by the interior boundaries of the input when it is not active. When the user activates the input, the full value becomes available and can be accessible via keyboard navigation or selection.

A single line of sample value text overflows the boundaries of the input field and is hidden beyond the field's rightmost edge.

Because of the accessibility issues that can result, placeholder text is not supported. When examples or additional instructions are needed, consider using the input's helper text or other supplemental text within the surrounding content.

Clear button

A clear button can be enabled to allow users a way to quickly remove a value from the input field. When enabled, the button remains hidden until a value is entered into the input field and then persistently displays until the user clears the value. While the icon and button styling can be customized, the button itself is a persistent part of the input functionality and therefore cannot be customized.

The input includes a label above a field that includes a sample value and a right-aligned icon that displays an X contained within a circle.

The clear button always precedes the right slot.

The input includes a label above a field that includes a sample value and a right-aligned icon that displays an X contained within a circle. A second icon is positioned immediately to the right of the circled X.

Right slot

The right slot can accommodate an icon to further describe the type of input required.

A sample icon is displayed to the right of a sample value to indicate the position of a right slot.

The right slot can also accommodate a button when a micro interaction is required within the input. Consider using small, tertiary, icon-only buttons for consistency and to compliment the rest of the input elements.

The top input includes a sample icon-only button without a container. The bottom input includes a sample icon-only button with a container and a focus ring. Both buttons are right-aligned within the field to indicate the position of a right slot.

When the slot is hidden, the input text expands to fill the available space.

Character count

A character counter can be displayed to provide feedback on character limitations for the input field as well how many characters are currently within the field.

A numeric counter is positioned below an input field and aligned to the right. The counter consists of a number representing the current number of characters in the field followed by a number representing the total number of characters allowed in the field. These two numbers are separated by a forward slash.

If a max length isn't provided, only the current character count is displayed.

A numeric counter displaying only the current number of characters is positioned below an input field and aligned to the right.

Behavior

States

Inputs have five available base states:

The input component includes enabled, focus, hover, active, and disabled states.
  1. Enabled
  2. Focus
  3. Hover
  4. Active
  5. Disabled

Invalid

Inputs can be set to invalid to indicate that a value needs to be entered or that the entered value is invalid. Error text is always displayed as part of the invalid state to allow for a generic error message or provide specific guidance as to what needs to be fixed. It is also displayed in addition to any helper text that is present and below the input field.

A sample of red error text is displayed immediately below the input field.

Error text wraps to a new line when it's too long for the available horizontal space.

The error text of the input wraps to a second line when it meets the edge of an implied container around the input.

Read-only

Inputs may be set to read-only for when form values need to be shown but shouldn’t be edited. Read-only content may still be copied by the user and hyperlinked content such as email addresses, URLs, and telephone numbers are still interactive. They are also part of the tab order and can receive focus.

An input is displayed with a label and sample value text. The input field has no visible border.

Figma

Creating new input types

The base input includes all of the functionality that is commonly found across various input types and is used to build out the other input types found within the system. If additional input types are needed, you can use the base input as a starting point and customize as needed.

Icon versus button

The left and right slots are primarily designed to accommodate icon and button components. Icons should be used in situations that are purely informative. For situations where interactivity is needed, an icon-only button should be used. When using a button, use element/jh-input-button which is included alongside jh-input. This is sized to appropriately fit within the input and represents how buttons will render in the input code.

Persisting slotted content

When switching input types, slotted icons and buttons may persist and override default content. For example, the default magnifying glass icon within the left slot of a search input will override the left slot of a different input type. To fix this, you can either drill down to the affected layer and reset it to the component defaults or ensure you’re starting with the correct input type.