Tooltip

The tooltip shows a short text hint next to its trigger on hover or focus, like explaining an icon-only button. It is for plain text only; for rich content or anything interactive, use a popover.

<button id="tooltip-demo-trigger" class="btn btn-outline">Hover</button>
 
<div class="tooltip" data-sp-toggle="#tooltip-demo-trigger">Add to library</div>

Usage

Add the tooltip class to an element and point it at its trigger with data-sp-toggle.

Class	Description
`tooltip`	Add to the hint element; carries the `data-sp-*` options

<!-- This is the trigger -->
<button id="my-trigger" class="btn btn-outline">Hover me</button>
 
<!-- This is the tooltip -->
<div class="tooltip" data-sp-toggle="#my-trigger">Add to library</div>

Examples

Side

Set which side the tooltip opens on with data-sp-placement; it defaults to top. It accepts any Floating UI placement and flips to the opposite side on its own when there isn't room.

<div class="flex flex-wrap justify-center gap-2">
  <button id="tooltip-left-trigger" class="btn btn-outline">Left</button>
  <button id="tooltip-top-trigger" class="btn btn-outline">Top</button>
  <button id="tooltip-bottom-trigger" class="btn btn-outline">Bottom</button>
  <button id="tooltip-right-trigger" class="btn btn-outline">Right</button>
</div>
 
<div
  class="tooltip"
  data-sp-toggle="#tooltip-left-trigger"
  data-sp-placement="left"
>
  Add to library
</div>
<div
  class="tooltip"
  data-sp-toggle="#tooltip-top-trigger"
  data-sp-placement="top"
>
  Add to library
</div>
<div
  class="tooltip"
  data-sp-toggle="#tooltip-bottom-trigger"
  data-sp-placement="bottom"
>
  Add to library
</div>
<div
  class="tooltip"
  data-sp-toggle="#tooltip-right-trigger"
  data-sp-placement="right"
>
  Add to library
</div>

With keyboard shortcut

A kbd rides along after the text; the tooltip tightens its padding for it and the kbd switches to a translucent treatment automatically.

<button
  id="tooltip-kbd-trigger"
  class="btn btn-outline btn-sm btn-icon"
  aria-label="Save"
>
  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15.2 3a2 2 0 0 1 1.4.6l3.8 3.8a2 2 0 0 1 .6 1.4V19a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2z"/><path d="M17 21v-7a1 1 0 0 0-1-1H8a1 1 0 0 0-1 1v7"/><path d="M7 3v4a1 1 0 0 0 1 1h7"/></svg>
</button>
 
<div class="tooltip" data-sp-toggle="#tooltip-kbd-trigger">
  Save Changes
  <kbd class="kbd">S</kbd>
</div>

Disabled button

Disabled elements don't fire pointer events, so wrap the trigger in a focusable span and point the tooltip at that.

<span id="tooltip-disabled-wrap" class="inline-block w-fit" tabindex="0">
  <button class="btn btn-outline" disabled>Disabled</button>
</span>
 
<div class="tooltip" data-sp-toggle="#tooltip-disabled-wrap">
  This feature is currently unavailable
</div>

RTL

Add dir="rtl" to any parent element, typically <html>, to render right-to-left. See the RTL guide for details.

<div id="tooltip-rtl-demo" dir="rtl">
  <div class="flex flex-wrap justify-center gap-2">
    <button id="tooltip-rtl-left-trigger" class="btn btn-outline" data-i18n="left">يسار</button>
    <button id="tooltip-rtl-top-trigger" class="btn btn-outline" data-i18n="top">أعلى</button>
    <button id="tooltip-rtl-bottom-trigger" class="btn btn-outline" data-i18n="bottom">أسفل</button>
    <button id="tooltip-rtl-right-trigger" class="btn btn-outline" data-i18n="right">يمين</button>
  </div>
 
  <div
    class="tooltip"
    data-sp-toggle="#tooltip-rtl-left-trigger"
    data-sp-placement="left"
  >
    <span data-i18n="content">إضافة إلى المكتبة</span>
  </div>
  <div
    class="tooltip"
    data-sp-toggle="#tooltip-rtl-top-trigger"
    data-sp-placement="top"
  >
    <span data-i18n="content">إضافة إلى المكتبة</span>
  </div>
  <div
    class="tooltip"
    data-sp-toggle="#tooltip-rtl-bottom-trigger"
    data-sp-placement="bottom"
  >
    <span data-i18n="content">إضافة إلى المكتبة</span>
  </div>
  <div
    class="tooltip"
    data-sp-toggle="#tooltip-rtl-right-trigger"
    data-sp-placement="right"
  >
    <span data-i18n="content">إضافة إلى المكتبة</span>
  </div>
</div>
 
<script>
  const translations = {
    ar: { dir: "rtl", left: "يسار", top: "أعلى", bottom: "أسفل", right: "يمين", content: "إضافة إلى المكتبة" },
    he: { dir: "rtl", left: "שמאל", top: "למעלה", bottom: "למטה", right: "ימין", content: "הוסף לספרייה" },
    en: { dir: "ltr", left: "Left", top: "Top", bottom: "Bottom", right: "Right", content: "Add to library" },
  };
  window.addEventListener("message", (e) => {
    const t = translations[e.data?.lang];
    if (e.data?.type !== "sp-language" || !t) return;
    document.getElementById("tooltip-rtl-demo").dir = t.dir;
    document.querySelectorAll("[data-i18n]").forEach((el) => {
      el.textContent = t[el.dataset.i18n];
    });
  });
</script>

Options

Set each option with its own data-sp-* attribute on the tooltip element.

Attribute	Values	Default
`data-sp-toggle`	CSS selector	—
`data-sp-placement`	Floating UI placement	`top`
`data-sp-offset`	Number	`5`

<div
  class="tooltip"
  data-sp-toggle="#my-trigger"
  data-sp-placement="right"
></div>

JavaScript

Events

Lifecycle events fire on the tooltip element; before* events are cancelable.

Event	When
`sp-beforeshow`	Before showing (cancelable)
`sp-show`	Showing
`sp-shown`	Shown and settled
`sp-beforehide`	Before hiding (cancelable)
`sp-hide`	Hiding
`sp-hidden`	Hidden

Methods

Get the instance with sp.tooltip(el), then call its methods:

Method	Description
`show()`	Show the tooltip
`hide()`	Hide the tooltip
`toggle()`	Show if hidden, else hide

const tooltip = sp.tooltip(document.querySelector("#my-tooltip"));
 
tooltip.show();