Contextual help

Contextual help provides users with information about the purpose and workings of a screen component.

Also known as: field help, field-level help, help icon, help text, help tooltip, hover help, info icon, info tooltip, inline guidance, inline help

Variations

Overlay - with label

Three digits on the back of most cards, four digits on the front of AMEX cards.

Code

<bolt-contextual-help label="What's this?" heading="Security Code">
    <p>Three digits on the back of most cards, four digits on the front of AMEX cards.</p>
</bolt-contextual-help>

Overlay - without label

Three digits on the back of most cards, four digits on the front of AMEX cards.

Code

<bolt-contextual-help heading="Security Code">
    <p>Three digits on the back of most cards, four digits on the front of AMEX cards.</p>
</bolt-contextual-help>

Embedding via help slot

Text field - with help slot

Help text body content

Code

<bolt-textfield label="Default text field">
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content
        <img src="images/placeholder-image.svg" alt=""></p>
    </bolt-contextual-help>
</bolt-textfield>

Select - with help slot

Help text body content

Code

<bolt-select label="Select menu name">
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content</p>
    </bolt-contextual-help>
    <option value="item1">Select menu item one</option>
    <option value="item2">Select menu item two</option>
    <option value="item3">Select menu item three</option>
</bolt-select>

Radio buttons - with help slot

Help text body content

First option

Second option

Last option

Code

<bolt-radio-group label="Radio button group" name="testname1">
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content</p>
    </bolt-contextual-help>
    <bolt-radio value="1">First option</bolt-radio>
    <bolt-radio value="2">Second option</bolt-radio>
    <bolt-radio value="3">Last option</bolt-radio>
</bolt-radio-group>

Checkbox - with help slot

Help text body content

Item 1 label

Item 2 label

Item 3 label

Code

<bolt-checkbox-group label="Non-required checkbox group" optionaltext="hide" name="controlName" >
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content</p>
    </bolt-contextual-help>
    <bolt-checkbox value="1">Item 1 label</bolt-checkbox>
    <bolt-checkbox value="2">Item 2 label</bolt-checkbox>
    <bolt-checkbox value="3">Item 3 label</bolt-checkbox>
</bolt-checkbox-group>

Textarea - with help slot

Help text body content

Code

<bolt-textarea label="Default text area">
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content</p>
    </bolt-contextual-help>
</bolt-textarea>

Autocomplete - with help slot

Help text body content

Code

<bolt-autocomplete onkeyup="setOptions(this)" label="Label">
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content</p>
    </bolt-contextual-help>
</bolt-autocomplete>

Date picker - with help slot

Help text body content

Code

<bolt-date-picker label="Date picker">
    <bolt-contextual-help slot="help" heading="Help text heading">
        <p>Help text body content</p>
    </bolt-contextual-help>
</bolt-date-picker>

Code reference

The Contextual help component can be used independently or embedded within certain components.

Elements

bolt-contextual-help

Properties

label (optional)
- The label that is shown next to the icon, either of which may be clicked to toggle the open/closed state.
arialabel (optional)
- Sets the aria-label attribute of the underlying <button> toggle.
arialabelledby (optional)
- Sets the aria-labelledby attribute of the underlying <button> toggle.
heading (optional)
- The bolded heading at the top of the contextual help content.
type (optional)
- overlay (default for standalone use)
  - Causes the contextual help content to appear in an overlay dialog at all screen sizes.
- push (default for slotted use)
  - Causes the contextual help content to appear inline below an input's label text at smaller screen sizes.
  - Must be manually configured when using HTML versions of Bolt components.
disabled (optional)
- When present, semantically disables the element, preventing users from viewing help content.

Events

The <bolt-contextual-help> custom element emits the following events:

bolt-contextual-help-opened: emitted when icon is clicked.

Use within other components

Parent slot configuration

The following components include a help slot, which allows consumers to customize HTML markup of a <bolt-contextual-help> child element:

Slotted <bolt-contextual-help> children of disabled parents will always be disabled.

Generic syntax:

<bolt-element-name ...>
  <bolt-contextual-help slot="help" ...>
    <!-- contextual help content -->
    ...
  </bolt-contextual-help>

  ...
</bolt-element-name>

Design guidelines

General guidelines

Contextual help is used to inform users why and/or how to use something.
Contextual help is automatically closed when users focus on another screen component.
Avoid Links inside Contextual help, especially those that that link to content outside the page. If a Link to content outside the page is needed, that content should open in a new tab so as to not disrupt the progress of the current flow.
When used with a field (like a Text Field, Select, or Autocomplete), a label for the Contextual Help is not recommended, however, it is possible to implement.

When to use

If the purpose or function of a screen component is not widely understood by users.

When not to use

Avoid using if the purpose or function of a screen component is commonly understood by users.
Avoid using Contextual help to display time-sensitive information to a user.

When to use something else

Consider other patterns if extensive information is needed for explanation to a user.

Do

Place Contextual help at the end of the element requiring guidance.
Use Contextual help for more detailed, non-critical guidance.
Align the caret tip center with the bottom-center of the Contextual help "trigger" button.

Don't

Don't use Contextual help in paragraphs of content.
Don't overlap the Contextual help trigger object.
Don't include critical information in Contextual help.
Don't include information in Contextual help if that information is already present elsewhere in the layout.

Content guidelines

Contextual help should use sentence case.
Content for inline Contextual help should be clear, direct, and use plain English.

Accessibility

WCAG 2.2 Compliant
JAWS 2025 Tested
NVDA 2025 Tested
VoiceOver Tested
Keyboard Tested
aXe Tested

Usage

Touch target size & spacing

When used inline with text, contextual help is not required to meet standard requirements for touch target sizes.
However, we recommend ensuring at least 4px of vertical spacing above and below <bolt-contextual-help> as a best practice to avoid proximity with other interactive elements.

Accessibility issues

In order for screenreaders to read the contextual help's content, you must wrap content in an HTML tag. For example a <p> tag.

All Bolt components have gone through accessibility testing, but please keep our accessibility guidelines in mind.

Core foundations

Theming

Scaling

Visual Style

Content design

Using Bolt

Styling

Web components

HTML patterns

Components

About Bolt

General

Contextual help

Embedding via help slot

Elements

bolt-contextual-help

Properties

Events

Use within other components

Parent slot configuration

General guidelines

When to use

When not to use

When to use something else

Do

Don't

Content guidelines

Usage

Touch target size & spacing

Accessibility issues

Display settings

Core foundations

Theming

Scaling

Visual Style

Content design

Using Bolt

Styling

Web components

HTML patterns

Components

About Bolt

General

Embedding via help slot

Elements

bolt-contextual-help

Properties

Events

Use within other components

Parent slot configuration

General guidelines

When to use

When not to use

When to use something else

Content guidelines

Accessibility compliance

Usage

Touch target size & spacing

Accessibility issues