Tooltip

Overview

ds-tooltip is a Web Component that renders an accessible tooltip using the Popover API. It supports both icon and text trigger modes, plain text and rich HTML content, customizable positioning, and hover/focus interactions with a minimum visible duration.

Options

Basic usage

By default, the simplest tooltip renders an info icon, with the content of the ds-tooltip displayed on hover as a tooltip.

html

Copy

<ds-tooltip>SIM ID identifies subscriber record.</ds-tooltip>

SIM ID identifies subscriber record.

Alternatively, for plain text tooltips the text attribute can be used instead of child elements.

html

Copy

<ds-tooltip text="Tooltip content"></ds-tooltip>

Text anchor

Set type="ds-text" and provide inline content to use a text as the anchor that triggers instead of an icon. The child text becomes the clickable trigger, and the text attribute provides the popover body.

html

Copy

<ds-tooltip type="ds-text" text="Tooltip content">Anchor text</ds-tooltip>

Anchor text

This works inline within an exising ds-text element as well:

html

Copy

<div class="ds-text">
  Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go
  with no commitments and all the tools you 
  <ds-tooltip type="ds-text" text="Tooltip content">need to manage</ds-tooltip>
  and secure your IoT network and devices.
</div>

Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.

Rich content

If you use the an icon anchor for the tooltip, the popover supports any HTML content, including structured layouts using SDS classes.

html

Copy

<ds-tooltip>
  <div class="ds-rows --indent-xsmall --gap-xsmall">
    <p class="ds-text --label">Subscriber details</p>
    <p class="ds-text --small">Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments.</p>
    <div class="ds-details">
      <dl>
        <dt>Status</dt>
        <dd><div>Active</div></dd>
      </dl>
      <dl>
        <dt>Plan</dt>
        <dd><div>plan-US</div></dd>
      </dl>
    </div>
  </div>
</ds-tooltip>

Subscriber details

Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments.

Status: Active

Plan: plan-US

Slotted content

Use slot="anchor" and slot="tip" for full control over both the trigger and popover content, including rich HTML with links and formatting.

html

Copy

<ds-tooltip>
  <div slot="anchor" class="ds-text">Anchor text</div>
  <div slot="tip" class="ds-rows --indent-xsmall --gap-xsmall">
    <p class="ds-text --label">Subscriber details</p>
    <p class="ds-text --small">Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments.</p>
    <div class="ds-details">
      <dl>
        <dt>Status</dt>
        <dd><div>Active</div></dd>
      </dl>
      <dl>
        <dt>Plan</dt>
        <dd><div>plan-US</div></dd>
      </dl>
    </div>
  </div>
</ds-tooltip>

Anchor text

Subscriber details

Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments.

Status: Active

Plan: plan-US

Size

Use the size attribute to control the trigger size. In icon mode, the default is xsmall.

html

Copy

<ds-tooltip size="2xsmall" text="2xsmall tooltip"></ds-tooltip>
<ds-tooltip text="Default (xsmall) tooltip"></ds-tooltip>
<ds-tooltip size="medium" text="Medium tooltip"></ds-tooltip>

In text mode, no default size is applied. Use size to explicitly set one.

html

Copy

<ds-tooltip type="ds-text" size="small" text="Small text tooltip">Small</ds-tooltip>
<ds-tooltip type="ds-text" text="Default text tooltip">Default</ds-tooltip>
<ds-tooltip type="ds-text" size="large" text="Large text tooltip">Large</ds-tooltip>

Small

Default

Large

Icons

Use the icon attribute to change the trigger icon.

html

Copy

<ds-tooltip icon="online-solid">
  <span>Status shows whether the subscriber is active.</span>
</ds-tooltip>

Status shows whether the subscriber is active.

Add the icon attribute to display a right-aligned icon alongside the text trigger.

html

Copy

<ds-tooltip type="ds-text" icon="question" text="Tooltip content">Anchor text</ds-tooltip>

Anchor text

Component colors

Use the color attribute to set the trigger color. Works in both icon and text modes.

html

Copy

<ds-tooltip icon="online-solid" color="celeste">
  <span>Status shows whether the subscriber is active.</span>
</ds-tooltip>

Status shows whether the subscriber is active.

html

Copy

<div class="ds-text">
  Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go
  with no commitments and all the tools you
  <ds-tooltip type="ds-text" color="celeste" text="Soracom provides tools for managing connectivity, security, and device lifecycle.">
    need to manage
  </ds-tooltip>
  and secure your IoT network and devices.
</div>

Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.

Position

The tooltip position defaults to top. Use the position attribute to change placement.

html

Copy

<ds-tooltip anchor-aria-label="Top (default)" position="top" text="Top position"></ds-tooltip>
<ds-tooltip anchor-aria-label="Bottom" position="bottom" text="Bottom position"></ds-tooltip>
<ds-tooltip anchor-aria-label="Left" position="left" text="Left position"></ds-tooltip>
<ds-tooltip anchor-aria-label="Right" position="right" text="Right position"></ds-tooltip>

All 12 positions are available:

The following positions are available - (hover over labels to view examples):

	Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.	Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.	Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.
Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.				Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.
Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.		Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.		Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.
Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.				Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.
	Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.	Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.	Global multicarrier cellular connectivity built for IoT & M2M. Pay as you go with no commitments and all the tools you need to manage and secure your IoT network and devices.

Attributes

Attribute	Values	Default	Description
`type`	`"ds-text"`, `"ds-icon"`	`ds-icon`	Sets the trigger mode. `"ds-text"` uses inline text as the trigger instead of an icon.
`text`	Plain text string	—	Sets the popover content as plain text. Used when no child elements provide popover content.
`anchor-aria-label`	String	`"Show tooltip"`	Sets the `aria-label` on the anchor/trigger element for accessibility. In text mode, defaults to empty.
`position`	See position table	`top`	Controls the tooltip placement relative to the trigger.
`icon`	SDS icon name	`info`	Sets the trigger icon (e.g. `online-solid`, `help`). Only applies in icon mode.
`size`	SDS size value	`xsmall` (icon mode only)	Sets the trigger size (e.g. `2xsmall`, `small`, `medium`). Applies in both icon and text modes.
`color`	SDS color name	—	Sets the trigger color (e.g. `celeste`, `magenta`). Applies in both icon and text modes.
`anchor-class`	CSS class string	—	Additional CSS classes appended to the trigger element.
`tip-class`	CSS class string	—	Additional CSS classes appended to the popover element.
`css`	`"shadow"`	Light DOM	Set to `"shadow"` to use Shadow DOM with self-loaded SDS stylesheets.

Slots

Slot	Description
`anchor`	Custom trigger content for text mode. Replaces the default text node as the trigger.
`tip`	Custom popover content. Supports rich HTML with links and formatting.
(default)	Child content without a slot attribute. Used as popover content in icon mode, or as trigger text in text mode (with `text` attribute providing the popover).

Behaviour

Shows on hover and keyboard focus
Remains visible for at least 500ms after the pointer leaves
Stays open while the pointer is over the popover content, allowing interaction with links
Automatically repositions when the viewport constrains the preferred position (e.g. a top tooltip flips to bottom if there is no room above)
Only one tooltip is visible at a time — opening a new tooltip closes any other
Closes when clicking outside the tooltip or pressing Escape
Uses the Popover API for proper layering and accessibility
Automatically wires aria-describedby between trigger and popover

Examples

Usage in a table header

html

Copy

<table class="ds-datatable --striped">
  <thead>
    <tr>
      <th>Name</th>
      <th>Status</th>
      <th>
        Plan
        <ds-tooltip anchor-aria-label="Show plan help" size="2xsmall" position="bottom">
          <span>The subscription plan assigned to this SIM.</span>
        </ds-tooltip>
      </th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>SIM-001</td>
      <td>Active</td>
      <td>plan-US</td>
    </tr>
    <tr>
      <td>SIM-002</td>
      <td>Inactive</td>
      <td>plan-K2</td>
    </tr>
  </tbody>
</table>

Name	Status	Plan The subscription plan assigned to this SIM.
SIM-001	Active	plan-US
SIM-002	Inactive	plan-K2

Usage in a label

html

Copy

<label class="ds-field">
  <div class="ds-text --label">
    SIM ID
    <ds-tooltip anchor-aria-label="Show SIM ID help" size="2xsmall">
      <span>The unique identifier assigned to the subscriber record.</span>
    </ds-tooltip>
  </div>
  <input class="ds-input" type="text" />
</label>

SIM ID The unique identifier assigned to the subscriber record.