Help text

Version 2.0.1

Help text provides either an informative description or an error message that gives more context about what a user needs to input. It’s commonly used in forms.

Key example of 2 required text fields using help text. First example, text field label Password. Help text description, Password must be at least 8 characters. Second example, text field with an error, label Password. Help text error message, Create a password with at least 8 characters.
DateVersionSpectrumExpress UI KitSep 13, 20222.0.1DownloadDownloadApr 06, 20222.0.0DownloadOct 20, 20201.0.0Download

Anatomy#

Image illustrating through labels the component parts of help text in context of a field, including one or more inputs, an optional icon communicating an error or alert, and text that is either a description or an error message.

Options#

Key examples of help text. 2 descriptions. wilson@adobe.com. Select the best way to contact you in case there’s an issue with your account. 2 error messages. Enter your email address. Select a contact method.

Text#

The text can accommodate either a description or an error message, giving extra context and guidance. Sometimes this communicates what to input or select, and sometimes it communicates how. It includes information such as:

  • An overall description of an input field or controls
  • Hints for what kind of information needs to be input or selected
  • Specific formatting examples or requirements

Regardless of the kind of message, it should be clear and concise. Use 1-2 short, complete sentences that end with a period (never an exclamation point). When showing formatting examples, it's not necessary to end with a period.

Key example of neutral and negative help text variants. Neutral variant shown in grey, text Password must be at least 8 characters. Negative variant shown in red, text Create a password with at least 8 characters.

Variant#

Help text has two variants: neutral and negative. The neutral variant is used to convey informative messages, while the negative variant is used to convey error messages.

Key example of With icon and Without icon help text variants. With icon variant shows a red triangle with an exclamation point, accompanying text in red, Select at least one interest. Without icon is only text in red, Select at least one interest.

Icon#

Help text using the negative variant can have an optional icon. In most cases, help text is used with a component that already displays an icon communicating an error (e.g., text field, text area, picker, combo box), so it’s not necessary to include another icon. In other cases, help text that is used with a component that does not display an icon communicating an error (e.g., checkbox group, radio group) needs to display an icon.

Key example of 4 sizes of help text, growing in size from small, medium, large, to extra-large. All 4 examples show a negative variant with an icon, text in red, Select at least one interest.

Size#

Help text comes in four different sizes: small, medium, large, and extra-large. The medium size is the default and most frequent option. Use the other sizes sparingly and pair them with components of the same size to respect the built-in hierarchy.

Key example of help text in a disabled state. A required text field in a disabled state, label Password. Help text description, Password must be at least 8 characters.

Disabled#

Help text using the neutral variant can be displayed in a disabled state. The text appears with a lighter gray that matches the style of other components in a disabled state. Help text using the negative variant cannot be displayed in a disabled state because it communicates an error, and error messages should not be visible when the component is disabled.

Table of options#

From the design point of view, each component has a number of options. These options and their names are platform agnostic, and each implementation should adapt these to fit into their framework.

PropertyValuesDefault Valuetexttext–variantneutral / negativeneutralhide iconyes / no
Only applicable if variant is negative.
nosizesmall / medium / large / extra-largemediumis disabled yes / no
Only applicable if variant is neutral.
no

Behaviors#

Key example of help text overflow behavior. Required text area, label Interests. Help text description, Describe the interests you’d like to explore through our tutorials.

Text overflow#

When the text is too long for the available horizontal space, it wraps to form another line.

Usage guidelines#

Use the optional icon depending on the accompanying component#

For the optional icon that can be displayed with the negative variant, usage depends on what kind of component the help text is accompanying.

For components such as text fields, text areas, pickers, and combo boxes, where there is already an icon communicating an error, it’s not necessary to include another icon. For checkbox groups or radio button groups, where there is no icon to communicate an error, include the optional icon.

do
Key example of correct usage of the optional icon. 2 examples. First example, a required picker in an error state with the icon inside the picker field, label Preferred contact method. Help text error message, Select a contact method. Second example, a required checkbox group in an error state with the icon accompanying the error message. Checkbox group label, Interests. 3 checkboxes, labels Travel, Music Shopping. Error message, Select at least one interest.
dont
Key example of incorrect usage of the optional icon. 2 examples. First example, a required picker in an error state with the icon inside the picker field, label Preferred contact method. Help text error message, Select a contact method, with another icon in-line with the error message. Second example, a required checkbox group in an error state but with no icon accompanying the error message. Checkbox group label, Interests. 3 checkboxes, labels Travel, Music Shopping. Error message, Select at least one interest.

Switch the help text description with an error message#

Help text displays either a description (the neutral variant) or an error message (the negative variant) in the same space. When a description is present and an error is triggered, it is replaced with an error message. Once the error is resolved, the help text description reappears.

Since one gets replaced by the other, the language of the help text description and the error need to work together to convey the same messaging. The description text explains the requirements or adds supplementary context for how to successfully interact with a component. The error message text tells a user how to fix the error by re-stating the interaction requirements. Make sure that the help text description and error message include the same essential information so that it isn’t lost if one replaces the other.

Learn how this applies to help text for text field, text area, combo box, and picker.

do
Key example of correct usage of how to switch the help text description with an error message. Required text field, Password. Description, Password must be at least 8 characters. Error message, Create a password with at least 8 characters.
dont
Key example of incorrect usage of how to switch the help text description with an error message. Required text field, Password. Description and error message using the same text, Password must be at least 8 characters.

Write error messages that show a solution#

Communicate error messages in a human-centered way by guiding a user and showing them a solution — don’t simply state what’s wrong and then leave them guessing as to how to resolve it. Ambiguous error messages can be frustrating and even shame-inducing for users. Also, keep in mind that something that a system may deem an error may not actually be perceived as an error to a user.

For help text, usually the error is related to something that needs to be fixed for in-line validation, so a helpful tone is most appropriate. For example, if someone were to miss filling out a required field that asks for their email address, write the error text like you’re offering a hint or a tip to help guide them to understand what needs to go in the missing field: “Enter your email address.”

Learn how this applies to help text for text field, text area, combo box, and picker.

do
Key example of how to write error messages that show a solution. 2 required text fields. First example, required text field, label Credit card number. Error message, Enter your credit card number. Second example, required text field, label Password. Error message, Create a password with at least 8 characters.
dont
Key example of error messages that are not helpful and do not show a solution. 2 required text fields. First example, required text field, label Credit card number. Error message, Invalid field. Second example, required text field, label Password. Error message, Password requirements not met!

Internationalization#

Key example of help text in right-to-left languages. An error message with text in red, with icon, in Arabic. Message, Select at least one interest.

RTL#

For RTL (right-to-left) languages, the layout of the help text is mirrored. The icon is placed on the right side of the text.

Changelog#

DateNumberNotesSep 13, 20222.0.1
  • Updated disabled text color (from gray-500 to gray-400)
Apr 06, 20222.0.0
  • Updated all colors to 6.0.0
Oct 20, 20201.0.0
  • This component has been added to the website

Design checklist#

check

All interactive states

Includes all interactive states that are applicable (hover, down, focus, keyboard focus, disabled).

check

All color themes

Works properly across all four color themes (lightest, light, dark, darkest).

check

All platform scales

Includes a desktop scale (UWP, macOS, web desktop) and a mobile scale (iOS, Android, web mobile).

check

Accessible use of color

Color is not used as the only visual means of conveying information (WCAG 2.0 1.4.1).

check

Accessible contrast for text

Text has a contrast ratio of at least 4.5:1 for small text and at least 3:1 for large text (WCAG 2.0 1.4.3).

N/A

Accessible contrast for UI components

Visual information required to identify components and states (except inactive components) has a contrast ratio of at least 3:1 (WCAG 2.1 1.4.11).

check

Content design

UI language and information design considerations have been incorporated into component design.

check

Defined options

Includes relevant options (variant, style, size, orientation, optional iconography, decorations, selection, error state, etc.)

check

Defined behaviors

Includes guidelines for keyboard focus, layout (wrapping, truncation, overflow), animation, interactions, etc.

check

Usage guidelines

Includes a list of dos and don'ts that highlight best practices and common mistakes.

check

Writing guidelines

Includes content standards or usage guidelines for how to write or format in-product content for the component.

check

Internationalization guidelines

Works properly across various locales and includes guidelines for bi-directionality (RTL).

N/A

Keyboard interactions

Follows WCAG 2.0 standards for keyboard accessibility guidelines and includes a description of the keyboard interactions.

check

Design tokens

All design attributes (color, typography, layout, animation, etc.) are available as design tokens.

N/A

UI kit

Includes a downloadable XD file that shows multiple options, states, color themes, and platform scales.

check

Generated UI kit

Includes a downloadable XD file, generated by code using design tokens defined in Spectrum DNA, and shows multiple options, states, color themes, and platform scales.

unchecked

In Spectrum for Adobe XD plugin

Component is included in the Spectrum for Adobe XD plugin.