Skip to main content
On this page

Tooltip

Show supplementary context for an interactive element on hover or focus.

When to use​

  • To provide supplementary, non-critical context for an interactive element, for example explaining what a button or field does when the label alone is ambiguous
  • To define a technical term or piece of industry jargon inline. Use DefinitionTooltip for this case.
  • To label an icon-only control where a visible text label is not possible. Use IconTooltip for this case.

When not to use​

  • For critical information - tooltips are not reliably accessible on touch devices and may be missed by keyboard users who do not explore every element. If users need the information to complete a task, show it in the interface.
  • To compensate for a poor label - if the trigger label needs a tooltip to be understood, improve the label instead.
  • For interactive content - tooltips cannot contain links, buttons, or other interactive elements. They do not receive focus and are not navigable.
  • For long or complex content - a tooltip should be short enough to read at a glance. For longer explanations, use a Disclosure instead.
  • As the only place information is documented - tooltips are not always reachable. Any information in a tooltip should also be available through another route.
  • For form field context - if you need to explain what to enter in a form field, use the hint text prop on the field component instead. Hint text is always visible and does not require discovery.

Anatomy​

  1. Trigger
  2. Tooltip

Basic usage​

Wrap any focusable element with TooltipTrigger and pass the tooltip content as the tooltip prop.

Loading...
Edit live code
<TooltipTrigger tooltip="Submits your meter reading">
  <PrimaryCTAButton>Submit reading</PrimaryCTAButton>
</TooltipTrigger>

Variants and features​

TooltipTrigger​

TooltipTrigger wraps any single focusable element and manages tooltip state. The child element is cloned with the necessary ARIA and event handler props. Any element that is not natively focusable (such as a div or span) will be given tabIndex=0 automatically.

A natively focusable child is used as-is:

Loading...
Edit live code
<TooltipTrigger tooltip="Submits your meter reading">
  <PrimaryCTAButton>Submit reading</PrimaryCTAButton>
</TooltipTrigger>

A child that is not natively focusable is given tabIndex=0, so it can still be reached by keyboard:

Loading...
Edit live code
<TooltipTrigger tooltip="Estimated from your last three readings">
  <span>1,204 kWh</span>
</TooltipTrigger>

DefinitionTooltip​

Use DefinitionTooltip when you need to define a term or phrase inline within body text. The trigger renders as the surrounding text with a dotted underline in colors.info, signalling that additional context is available.

Loading...
Edit live code
<P> This is a paragraph <DefinitionTooltip tooltip="This is the tooltip content">with a tooltip</DefinitionTooltip></P>

IconTooltip​

Use IconTooltip to add a supplementary information tooltip next to a label or heading. It renders a hardcoded info icon button. The icon and button cannot be customised. If you need a different trigger, use TooltipTrigger directly.

Loading...
Edit live code
<P>Standing charge <IconTooltip tooltip="A fixed daily amount, charged whether or not you use any energy" /></P>

Placement​

Tooltips default to appearing below the trigger. Use placement to change the direction. Collision detection runs automatically for top and bottom placements. The tooltip shifts horizontally if it would overflow the window or a boundary element.

Loading...
Edit live code
<Cluster spaceBetween={4}>
  <ClusterItem>
    <TooltipTrigger tooltip="Above the trigger" placement="top">
      <SecondaryCTAButton>Top</SecondaryCTAButton>
    </TooltipTrigger>
  </ClusterItem>
  <ClusterItem>
    <TooltipTrigger tooltip="Below the trigger (default)" placement="bottom">
      <SecondaryCTAButton>Bottom</SecondaryCTAButton>
    </TooltipTrigger>
  </ClusterItem>
  <ClusterItem>
    <TooltipTrigger tooltip="Left of the trigger" placement="left">
      <SecondaryCTAButton>Left</SecondaryCTAButton>
    </TooltipTrigger>
  </ClusterItem>
  <ClusterItem>
    <TooltipTrigger tooltip="Right of the trigger" placement="right">
      <SecondaryCTAButton>Right</SecondaryCTAButton>
    </TooltipTrigger>
  </ClusterItem>
</Cluster>

Tooltip boundary​

By default, collision detection uses the window width as the boundary. To constrain the tooltip within a specific container, for example a panel or modal, add the data-nebula-tooltip-boundary attribute to that ancestor element.

Loading...
Edit live code
<Card data-nebula-tooltip-boundary>
  <Cluster spaceBetween={2} justify="flex-end">
    <ClusterItem>
      <TooltipTrigger tooltip="This tooltip shifts to stay inside the card rather than the window">
        <SecondaryCTAButton>Near the edge</SecondaryCTAButton>
      </TooltipTrigger>
    </ClusterItem>
  </Cluster>
</Card>

Accessible name vs description​

The relationship prop controls how the tooltip content is announced by screen readers.

  • description (default): the tooltip provides supplementary context. The trigger has its own visible label; the tooltip describes it. Screen readers announce both the label and the tooltip.
  • label: the tooltip is the accessible name of the trigger. Use this when the trigger has no other visible label, for example an icon-only button. The tooltip content replaces the trigger's accessible name.

The trigger has its own visible label, so the tooltip describes it:

Loading...
Edit live code
<TooltipTrigger tooltip="Sends the reading to your supplier" relationship="description">
  <PrimaryCTAButton>Submit reading</PrimaryCTAButton>
</TooltipTrigger>

The trigger has no visible label, so the tooltip becomes its accessible name:

Loading...
Edit live code
<TooltipTrigger tooltip="Gas supply" relationship="label">
  <Icon name="gas" size="2em" />
</TooltipTrigger>

Delay​

Tooltips appear after a 100ms delay by default. Set delay={true} to use a 1500ms delay, appropriate when tooltips might be triggered accidentally during normal page interaction.

Loading...
Edit live code
<Cluster spaceBetween={4}>
  <ClusterItem>
    <TooltipTrigger tooltip="Appears after 100ms">
      <SecondaryCTAButton>Default delay</SecondaryCTAButton>
    </TooltipTrigger>
  </ClusterItem>
  <ClusterItem>
    <TooltipTrigger tooltip="Appears after 1500ms" delay>
      <SecondaryCTAButton>Long delay</SecondaryCTAButton>
    </TooltipTrigger>
  </ClusterItem>
</Cluster>