Tooltip

Tooltips are used to provide additional information or context for a UI element, clarify the purpose or function of a UI element, or indicate the meaning of an icon or symbol.

Usage

When to use

When displaying additional context or information that is not critical to the user’s task or decision-making process.

When not to use

• When the content is too lengthy or complex.
• When the information provided is critical to the user’s task or decision-making process, consider moving the content to the page or an alert.

Placement

Tooltips can be placed in various positions relative to the UI element they are associated with. Choose the placement based on the context and available space around the tooltip trigger.

The most common options are: top, bottom, left, right.

The tooltip supports additional placement options: top-start, top-end, bottom-start, bottom-end, left-start, left-end, right-start, right-end.

Offset

The default and recommended distance between the trigger and the tooltip’s pointer is 4px.

Content

The tooltip should contain text only. Basic text formatting, such as bold and italic, is supported.

If more complex content is necessary to convey the information, consider other display components or moving the content to the page.

Text overflow

The text should wrap when it exceeds a maximum width of 280px. There is no character limit, but we recommend keeping it short and concise (~80 characters).

How to use this component

The HDS tooltip is provided as both a TooltipButton component and as an hds-tooltip Ember modifier. To be accessible, the element which triggers a tooltip needs to be an interactive element which can receive focus. This means that:

• if the tooltip needs to be applied to a non-interactive element, the TooltipButton component should be used as it wraps the opener element with a button element.
• if the tooltip needs to be applied to an element which is already interactive, the hds-tooltip modifier should be used.

Currently, the tooltip uses Tippy.js under the hood for its main functionality.

TooltipButton

Icon

<Hds::TooltipButton @text="Hello!" aria-label="More information">
  <Hds::Icon @name="info" />
</Hds::TooltipButton>

Inline with text

<h4 class="hds-typography-display-100">
  Header text
  <Hds::TooltipButton @text="Hello!" aria-label="More information">
    <Hds::Icon @name="info" />
  </Hds::TooltipButton>
</h4>

Placement

The tooltip appears at the “top” centered above the opener button content by default. If the tooltip is near any of the edges of the screen, its position will automatically adjust to prevent the tooltip content from being cut off so it remains readable.

Use the @placement argument if you would like to use a different starting position for the tooltip vs. the default.

<Hds::TooltipButton @text="Hello!" @placement="right">
  <Hds::Badge @text="Some tests failed" @icon="alert-triangle" @color="warning" />
</Hds::TooltipButton>

Offset

You can change the offset of the tooltip in relation to the opener element content if needed.

<Hds::TooltipButton @text="Hello!" @offset={{array 50 30}}>
  <Hds::Stepper::Step::Indicator @text="1" @status="incomplete" />
</Hds::TooltipButton>

isInline

You can change the default inline-block display to use flex display if needed.

<p>
  Text before
  <Hds::TooltipButton
    @text="Hello!"
    aria-label="HashiCorp"
    @isInline={{false}}
  >
    <Hds::Icon @name="hashicorp" />
  </Hds::TooltipButton>
  Text after
</p>

Extra Tippy Options

You can use @extraTippyOptions to provide more specific options to Tippy.js. For a full list of available options refer to the Tippy.js API documentation.

For example, you can use the allowHTML option to enable rich tooltip text:

<Hds::TooltipButton
  @extraTippyOptions={{hash allowHTML=true}}
  @text="<b>Hello</b> <em>there</em>!"
>
  More information
</Hds::TooltipButton>

Ember modifier

An Ember modifier is available if your use case requires attaching a tooltip to an element that is already interactive (to be accessible, tooltips should only be attached to interactive elements, like buttons, links, inputs, etc).

Modifier used on a link

<Hds::Link::Standalone
  {{hds-tooltip "Hello!"}}
  @href="#"
  @icon="collections"
  @text="Read tutorial"
/>

Placement

<Hds::Button
  {{hds-tooltip "Hello!"
  options=(hash placement="right")}}
  @icon="external-link"
  @text="Visit website"
  @href="https://hashicorp.com"
/>

Offset

<Hds::Form::Field @layout="vertical" as |F|>
  <F.Label @controlId="tooltip-example-control-id">First Name</F.Label>
  <F.Control>
    <Hds::Form::TextInput::Base
      {{hds-tooltip "Hello!"
      options=(hash placement="top"
      offset=(array 0 30))}}
      @type="text"
      @value="Jane"
      id="tooltip-example-control-id"
      @width="200px"
    />
  </F.Control>
</Hds::Form::Field>

Extra Tippy Options

You can enable extra Tippy.js options by passing a hash of the options you wish to use similarly to how the TooltipButton component works. You should make sure that any additional options chosen will still result in a WCAG-conformant outcome.

For example, this is how to enable rich text in the case of the modifier:

<p class="hds-typography-body-300">
  <a
    href="#"
    {{hds-tooltip "<b>Hello</b>!" options=(hash allowHTML=true)}}
  >
    More information
  </a>
</p>

Component API

TooltipButton

hds-tooltip modifier

The modifier offers the same options as the component. See the “How to use” section for syntax examples.

Anatomy

Conformance rating

When used on an interactive element, there should be no conformance issues with this component.

The issue with tooltips, in general, is that of persistence and perceivability. When used on inline text, how does the user know that the text has some sort of tooltip attached to it? If the user cannot perceive that the text has any kind of interactivity, then the tooltip would, in this case, not be conformant.

Consumers should proceed with caution in this case, and consider designs that make it clear to the user what options are available to them.

Focus

• When the trigger receives focus via keyboard, the tooltip shows.
• When the user presses the ESC key, the tooltip dismisses and gets removed from the screen.

Applicable WCAG Success Criteria

This section is for reference only. This component intends to conform to the following WCAG Success Criteria:

Support

If any accessibility issues have been found within this component, let us know by submitting an issue.