sp-help-text

NPM 1.0.1

View Storybook
Overview API Changelog

Overview

An <sp-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.

Usage

Usage

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/help-text

Import the side effectful registration of <sp-help-text> via:

import '@spectrum-web-components/help-text/sp-help-text.js';

When looking to leverage the HelpText base class as a type and/or for extension purposes, do so via:

import { HelpText } from '@spectrum-web-components/help-text';

Options

Sizes

Small 
<sp-field-label size="s" for="size-s">Password</sp-field-label>
<sp-textfield size="s" id="size-s" type="password">
    <sp-help-text size="s" slot="help-text">
        Create a password with at least 8 characters.
    </sp-help-text>
</sp-textfield>
 Medium 
<sp-field-label size="m" for="size-m">Password</sp-field-label>
<sp-textfield size="m" id="size-m" type="password">
    <sp-help-text size="m" slot="help-text">
        Create a password with at least 8 characters.
    </sp-help-text>
</sp-textfield>
 Large 
<sp-field-label size="l" for="size-l">Password</sp-field-label>
<sp-textfield size="l" id="size-l" type="password">
    <sp-help-text size="l" slot="help-text">
        Create a password with at least 8 characters.
    </sp-help-text>
</sp-textfield>
 Extra Large 
<sp-field-label size="xl" for="size-xl">Password</sp-field-label>
<sp-textfield size="xl" id="size-xl" type="password">
    <sp-help-text size="xl" slot="help-text">
        Create a password with at least 8 characters.
    </sp-help-text>
</sp-textfield>

Negative

The negative variant of <sp-help-text> is used to convey error messages.

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.

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.”

<sp-field-label for="negative">Password</sp-field-label>
<sp-textfield id="negative" type="password" required invalid>
    <sp-help-text slot="help-text">
        Create a password with at least 8 characters.
    </sp-help-text>
    <sp-help-text variant="negative" slot="help-text-negative">
        Passwords must be at least 8 characters
    </sp-help-text>
</sp-textfield>
Icon

When associated with content that does not supply an icon outlining the presence of an error, use the icon attribute to display one as part of the <sp-help-text> element.

<sp-field-group horizontal id="fruit">
    <sp-checkbox value="apple">Apple</sp-checkbox>
    <sp-checkbox
        value="not-a-fruit"
        onchange="javascript:this.parentElement.invalid = this.checked"
    >
        Lettuce
    </sp-checkbox>
    <sp-checkbox value="strawberry" checked>Strawberry</sp-checkbox>
    <sp-help-text slot="help-text">One of these is not a fruit.</sp-help-text>
    <sp-help-text icon slot="negative-help-text" icon>
        Choose actual fruit(s).
    </sp-help-text>
</sp-field-group>

Disabled

When the content associated to the element is disabled, use the disabled attribute to match the delivery of the <sp-help-text> element to that content.

<sp-field-label for="color" disabled>Color</sp-field-label>
<sp-combobox id="color" disabled>
    <sp-menu-item value="red">Red</sp-menu-item>
    <sp-menu-item value="green">Green</sp-menu-item>
    <sp-menu-item value="blue">Blue</sp-menu-item>
    <sp-help-text slot="help-text" disabled>
        Choose or add at least one color.
    </sp-help-text>
</sp-combobox>

Accessibility

It is not currently possible to provide accessible ARIA references between elements in different shadow roots, so help text must be used in the help-text or help-text-negative slot of a <sp-text-field>, <sp-field-group>, <sp-combobox> or <sp-picker>.

To add help text to your own custom element, see Help Text Mixin.

Attributes and Properties

Property Attribute Type Default Description icon icon boolean false variant variant HelpTextVariants 'neutral' The visual variant to apply to this help text.

1.0.1 (2024-11-11)

Note: Version bump only for package @spectrum-web-components/help-text

1.0.0 (2024-10-31)

Bug Fixes

  • help-text: apply aria-live to ensure full help text is read to user (#4210) (049dc56)

0.49.0 (2024-10-15)

Note: Version bump only for package @spectrum-web-components/help-text

0.48.1 (2024-10-01)

Note: Version bump only for package @spectrum-web-components/help-text

0.48.0 (2024-09-17)

Note: Version bump only for package @spectrum-web-components/help-text

0.47.2 (2024-09-03)

Note: Version bump only for package @spectrum-web-components/help-text

0.47.1 (2024-08-27)

Note: Version bump only for package @spectrum-web-components/help-text

0.47.0 (2024-08-20)

Note: Version bump only for package @spectrum-web-components/help-text

0.46.0 (2024-08-08)

Note: Version bump only for package @spectrum-web-components/help-text

0.45.0 (2024-07-30)

Note: Version bump only for package @spectrum-web-components/help-text

0.44.0 (2024-07-15)

Note: Version bump only for package @spectrum-web-components/help-text

0.43.0 (2024-06-11)

Note: Version bump only for package @spectrum-web-components/help-text

0.42.5 (2024-05-24)

Note: Version bump only for package @spectrum-web-components/help-text

0.42.4 (2024-05-14)

Note: Version bump only for package @spectrum-web-components/help-text

0.42.3 (2024-05-01)

Note: Version bump only for package @spectrum-web-components/help-text

0.42.2 (2024-04-03)

Note: Version bump only for package @spectrum-web-components/help-text

0.42.1 (2024-04-02)

Note: Version bump only for package @spectrum-web-components/help-text

0.42.0 (2024-03-19)

Features

  • asset: use core tokens (99e76f4)

0.41.2 (2024-03-05)

Note: Version bump only for package @spectrum-web-components/help-text

0.41.1 (2024-02-22)

Note: Version bump only for package @spectrum-web-components/help-text

0.41.0 (2024-02-13)

Note: Version bump only for package @spectrum-web-components/help-text

0.40.5 (2024-02-05)

Note: Version bump only for package @spectrum-web-components/help-text

0.40.4 (2024-01-29)

Note: Version bump only for package @spectrum-web-components/help-text

0.40.3 (2024-01-11)

Note: Version bump only for package @spectrum-web-components/help-text

0.40.2 (2023-12-18)

Note: Version bump only for package @spectrum-web-components/help-text

0.40.1 (2023-12-05)

Note: Version bump only for package @spectrum-web-components/help-text

0.40.0 (2023-11-16)

Note: Version bump only for package @spectrum-web-components/help-text

0.39.4 (2023-11-02)

Note: Version bump only for package @spectrum-web-components/help-text

0.39.3 (2023-10-18)

Note: Version bump only for package @spectrum-web-components/help-text

0.39.2 (2023-10-13)

Note: Version bump only for package @spectrum-web-components/help-text

0.39.1 (2023-10-06)

Note: Version bump only for package @spectrum-web-components/help-text

0.39.0 (2023-09-25)

Note: Version bump only for package @spectrum-web-components/help-text

0.38.0 (2023-09-05)

Note: Version bump only for package @spectrum-web-components/help-text

0.37.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/help-text

0.36.0 (2023-08-18)

Note: Version bump only for package @spectrum-web-components/help-text

0.35.0 (2023-07-31)

Note: Version bump only for package @spectrum-web-components/help-text

0.34.0 (2023-07-11)

Note: Version bump only for package @spectrum-web-components/help-text

0.33.2 (2023-06-14)

Note: Version bump only for package @spectrum-web-components/help-text

0.33.0 (2023-06-08)

Note: Version bump only for package @spectrum-web-components/help-text

0.32.0 (2023-06-01)

Note: Version bump only for package @spectrum-web-components/help-text

0.31.0 (2023-05-17)

Note: Version bump only for package @spectrum-web-components/help-text

0.30.0 (2023-05-03)

Bug Fixes

  • dialog: updates for delivering dialog content accessibly (f0ed33c)

Features

  • add Help Text pattern (fdbb812)
  • include all Dev Mode files in side effects (f70817c)
  • shared pkg versions, devmode define warning, registry-conflicts docs (6e49565)

0.2.14 (2023-04-24)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.13 (2023-04-05)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.12 (2023-03-22)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.11 (2023-03-08)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.10 (2023-02-08)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.9 (2023-01-23)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.8 (2023-01-09)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.7 (2022-12-08)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.6 (2022-11-21)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.5 (2022-11-14)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.4 (2022-10-28)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.3 (2022-10-10)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.2 (2022-09-14)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.1 (2022-08-24)

Note: Version bump only for package @spectrum-web-components/help-text

0.2.0 (2022-08-09)

Features

  • include all Dev Mode files in side effects (f70817c)

0.1.11 (2022-08-04)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.10 (2022-07-18)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.9 (2022-06-29)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.8 (2022-06-07)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.7 (2022-05-27)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.6 (2022-05-12)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.5 (2022-04-21)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.4 (2022-03-08)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.3 (2022-03-04)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.2 (2022-02-22)

Bug Fixes

  • dialog: updates for delivering dialog content accessibly (f0ed33c)

0.1.1 (2022-01-26)

Note: Version bump only for package @spectrum-web-components/help-text

0.1.0 (2021-12-13)

Features

  • add Help Text pattern (fdbb812)