label and hideLabel

Text fields should always have an accessible name, typically provided by a visible text label. In rare cases where context is sufficient and an accessibility expert has reviewed the design, the visible label may be hidden or omitted. When no visible label is present, the input must still expose an accessible name (for example, in HTML via "aria-label" or "aria-labelledby," and on other platforms via the platform's accessible-name mechanism).

labelPosition

Labels can be placed either on top or on the side. Top labels are the default and are recommended because they work better with long copy, localization, and responsive layouts. Side labels are most useful when vertical space is limited.

value

The value shows a user's entered text.

width

The text field's default width is field-default-width-[small/medium/large/extra-large].

size

Text fields come in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequently used option. Use the other sizes sparingly; they should be used to create a hierarchy of importance within the page.

isRequired and necessityIndicator

Text fields can be marked as optional or required, depending on the situation. For required text fields, there are two styling options: a "(required)" label or an asterisk. If you use an asterisk, be sure to include hint text to explain what the asterisk means. Optional text fields are either denoted with text added to the end of the label — "(optional)" — or have no indication at all.

The asterisk used in this component is an icon that has specific spacing from the label text — not part of the label text itself.

hasCharacterCount

Text fields can display a character count indicator when the length of the text entry needs to be kept under a predefined value. Character count indicators can be used in conjunction with other indicators (validation icon, "optional" or "required" indicators) when necessary.

showValidIcon

Text fields can display a validation icon when the text entry is expected to conform to a specific format such as email address, credit card number, password creation requirements, and many more. The icon appears as soon as a user types a valid entry in the field.

isError

A text field can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. If an error exists, the error icon always overrides the validation icon.

isDisabled

A text field in a disabled state shows that an text field exists, but is not available in that circumstance. This can be used to maintain layout continuity and communicate that a field may become available later.

helpText

A text field can have help text below the field to give extra context or instruction about what a user should input in the field. The help text communicates a hint or helpful information, such as specific requirements for correctly filling out the field.

errorMessage

A text field can be marked as having an error to show that a value needs to be entered in order to move forward or that a value that was entered is invalid. The error message communicates an error for when the field requirements aren't met, prompting a user to adjust what they had originally input. If an error exists, the error icon always overrides the validation icon.