On this page
Examples
Basic Tooltip
Placement
Click Trigger
Manual Trigger
Removing Arrows
HTML in Tooltips
Setting a Maximum Width
Hoisting
Usage guidelines
Importing
Slots
Properties
Events
Methods
Custom Properties
Parts
Animations
Dependencies

Since Shoelace 2.0

Code stable

Pattern stable

Figma ready

Tooltip

<sl-tooltip> | SlTooltip

Tooltips display additional information based on a specific action.

Examples

Tooltips appear when a user hovers or focuses an element. They provide contextual information about the element they are paired with.

A tooltip’s target is its first child element, so you should only wrap one element inside of the tooltip. If you need the tooltip to show up for multiple elements, nest them inside a container first.

Tooltips use display: contents so they won’t interfere with how elements are positioned in a flex or grid layout.

Hover Me

<sl-tooltip content="This is a tooltip">
  <sl-button>Hover Me</sl-button>
</sl-tooltip>

sl-tooltip content="This is a tooltip"
  sl-button Hover Me

import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const App = () => (
  <SlTooltip content="This is a tooltip">
    <SlButton>Hover Me</SlButton>
  </SlTooltip>
);

Placement

Use the placement attribute to set the preferred placement of the tooltip.

Note: The default placement of tooltips in our Design System is top.

<div class="tooltip-placement-example">
  <div class="tooltip-placement-example-row">
    <sl-tooltip content="top-start" placement="top-start">
      <sl-button></sl-button>
    </sl-tooltip>

    <sl-tooltip content="top" placement="top">
      <sl-button></sl-button>
    </sl-tooltip>

    <sl-tooltip content="top-end" placement="top-end">
      <sl-button></sl-button>
    </sl-tooltip>
  </div>

  <div class="tooltip-placement-example-row">
    <sl-tooltip content="left-start" placement="left-start">
      <sl-button></sl-button>
    </sl-tooltip>

    <sl-tooltip content="right-start" placement="right-start">
      <sl-button></sl-button>
    </sl-tooltip>
  </div>

  <div class="tooltip-placement-example-row">
    <sl-tooltip content="left" placement="left">
      <sl-button></sl-button>
    </sl-tooltip>

    <sl-tooltip content="right" placement="right">
      <sl-button></sl-button>
    </sl-tooltip>
  </div>

  <div class="tooltip-placement-example-row">
    <sl-tooltip content="left-end" placement="left-end">
      <sl-button></sl-button>
    </sl-tooltip>

    <sl-tooltip content="right-end" placement="right-end">
      <sl-button></sl-button>
    </sl-tooltip>
  </div>

  <div class="tooltip-placement-example-row">
    <sl-tooltip content="bottom-start" placement="bottom-start">
      <sl-button></sl-button>
    </sl-tooltip>

    <sl-tooltip content="bottom" placement="bottom">
      <sl-button></sl-button>
    </sl-tooltip>

    <sl-tooltip content="bottom-end" placement="bottom-end">
      <sl-button></sl-button>
    </sl-tooltip>
  </div>
</div>

<style>
  .tooltip-placement-example {
    width: 250px;
    margin: 1rem;
  }

  .tooltip-placement-example-row:after {
    content: '';
    display: table;
    clear: both;
  }

  .tooltip-placement-example sl-button {
    float: left;
    width: 2.5rem;
    margin-right: 0.25rem;
    margin-bottom: 0.25rem;
  }

  .tooltip-placement-example-row:nth-child(1) sl-tooltip:first-child sl-button,
  .tooltip-placement-example-row:nth-child(5) sl-tooltip:first-child sl-button {
    margin-left: calc(40px + 0.25rem);
  }

  .tooltip-placement-example-row:nth-child(2) sl-tooltip:nth-child(2) sl-button,
  .tooltip-placement-example-row:nth-child(3) sl-tooltip:nth-child(2) sl-button,
  .tooltip-placement-example-row:nth-child(4) sl-tooltip:nth-child(2) sl-button {
    margin-left: calc((40px * 3) + (0.25rem * 3));
  }
</style>

div class="tooltip-placement-example"
  div class="tooltip-placement-example-row"
    sl-tooltip content="top-start" placement="top-start"
      sl-button
    sl-tooltip content="top" placement="top"
      sl-button
    sl-tooltip content="top-end" placement="top-end"
      sl-button
  div class="tooltip-placement-example-row"
    sl-tooltip content="left-start" placement="left-start"
      sl-button
    sl-tooltip content="right-start" placement="right-start"
      sl-button
  div class="tooltip-placement-example-row"
    sl-tooltip content="left" placement="left"
      sl-button
    sl-tooltip content="right" placement="right"
      sl-button
  div class="tooltip-placement-example-row"
    sl-tooltip content="left-end" placement="left-end"
      sl-button
    sl-tooltip content="right-end" placement="right-end"
      sl-button
  div class="tooltip-placement-example-row"
    sl-tooltip content="bottom-start" placement="bottom-start"
      sl-button
    sl-tooltip content="bottom" placement="bottom"
      sl-button
    sl-tooltip content="bottom-end" placement="bottom-end"
      sl-button

css:
  .tooltip-placement-example {
  width: 250px;
  margin: 1rem;
  }

  .tooltip-placement-example-row:after {
  content: ;
  display: table;
  clear: both;
  }

  .tooltip-placement-example sl-button {
  float: left;
  width: 2.5rem;
  margin-right: 0.25rem;
  margin-bottom: 0.25rem;
  }

  .tooltip-placement-example-row:nth-child(1) sl-tooltip:first-child sl-button,
  .tooltip-placement-example-row:nth-child(5) sl-tooltip:first-child sl-button {
  margin-left: calc(40px + 0.25rem);
  }

  .tooltip-placement-example-row:nth-child(2) sl-tooltip:nth-child(2) sl-button,
  .tooltip-placement-example-row:nth-child(3) sl-tooltip:nth-child(2) sl-button,
  .tooltip-placement-example-row:nth-child(4) sl-tooltip:nth-child(2) sl-button {
  margin-left: calc((40px * 3) + (0.25rem * 3));
  }

import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const css = `
  .tooltip-placement-example {
    width: 250px;
  }

  .tooltip-placement-example-row:after {
    content: '';
    display: table;
    clear: both;
  }

  .tooltip-placement-example sl-button {
    float: left;
    width: 2.5rem;
    margin-right: 0.25rem;
    margin-bottom: 0.25rem;
  }

  .tooltip-placement-example-row:nth-child(1) sl-tooltip:first-child sl-button,
  .tooltip-placement-example-row:nth-child(5) sl-tooltip:first-child sl-button {
    margin-left: calc(40px + 0.25rem);
  }

  .tooltip-placement-example-row:nth-child(2) sl-tooltip:nth-child(2) sl-button,
  .tooltip-placement-example-row:nth-child(3) sl-tooltip:nth-child(2) sl-button,
  .tooltip-placement-example-row:nth-child(4) sl-tooltip:nth-child(2) sl-button {
    margin-left: calc((40px * 3) + (0.25rem * 3));
  }
`;

const App = () => (
  <>
    <div className="tooltip-placement-example">
      <div className="tooltip-placement-example-row">
        <SlTooltip content="top-start" placement="top-start">
          <SlButton />
        </SlTooltip>

        <SlTooltip content="top" placement="top">
          <SlButton />
        </SlTooltip>

        <SlTooltip content="top-end" placement="top-end">
          <SlButton />
        </SlTooltip>
      </div>

      <div className="tooltip-placement-example-row">
        <SlTooltip content="left-start" placement="left-start">
          <SlButton />
        </SlTooltip>

        <SlTooltip content="right-start" placement="right-start">
          <SlButton />
        </SlTooltip>
      </div>

      <div className="tooltip-placement-example-row">
        <SlTooltip content="left" placement="left">
          <SlButton />
        </SlTooltip>

        <SlTooltip content="right" placement="right">
          <SlButton />
        </SlTooltip>
      </div>

      <div className="tooltip-placement-example-row">
        <SlTooltip content="left-end" placement="left-end">
          <SlButton />
        </SlTooltip>

        <SlTooltip content="right-end" placement="right-end">
          <SlButton />
        </SlTooltip>
      </div>

      <div className="tooltip-placement-example-row">
        <SlTooltip content="bottom-start" placement="bottom-start">
          <SlButton />
        </SlTooltip>

        <SlTooltip content="bottom" placement="bottom">
          <SlButton />
        </SlTooltip>

        <SlTooltip content="bottom-end" placement="bottom-end">
          <SlButton />
        </SlTooltip>
      </div>
    </div>

    <style>{css}</style>
  </>
);

Click Trigger

Set the trigger attribute to click to toggle the tooltip on click instead of hover.

Click to Toggle

<sl-tooltip content="Click again to dismiss" trigger="click">
  <sl-button>Click to Toggle</sl-button>
</sl-tooltip>

sl-tooltip content="Click again to dismiss" trigger="click"
  sl-button Click to Toggle

import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const App = () => (
  <SlTooltip content="Click again to dismiss" trigger="click">
    <SlButton>Click to Toggle</SlButton>
  </SlTooltip>
);

Manual Trigger

Tooltips can be controlled programmatically by setting the trigger attribute to manual. Use the open attribute to control when the tooltip is shown.

Toggle Manually

<sl-button style="margin-right: 4rem;">Toggle Manually</sl-button>

<sl-tooltip content="This is an avatar" trigger="manual" class="manual-tooltip">
  <sl-avatar label="User"></sl-avatar>
</sl-tooltip>

<script>
  const tooltip = document.querySelector('.manual-tooltip');
  const toggle = tooltip.previousElementSibling;

  toggle.addEventListener('click', () => (tooltip.open = !tooltip.open));
</script>

sl-button style="margin-right: 4rem;" Toggle Manually
sl-tooltip.manual-tooltip content="This is an avatar" trigger="manual"
  sl-avatar label="User"

javascript:
  const tooltip = document.querySelector(.manual-tooltip);
  const toggle = tooltip.previousElementSibling;

  toggle.addEventListener(click, () => (tooltip.open = !tooltip.open));

import { useState } from 'react';
import SlAvatar from '@teamshares/shoelace/dist/react/avatar';
import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const App = () => {
  const [open, setOpen] = useState(false);

  return (
    <>
      <SlButton style={{ marginRight: '4rem' }} onClick={() => setOpen(!open)}>
        Toggle Manually
      </SlButton>

      <SlTooltip open={open} content="This is an avatar" trigger="manual">
        <SlAvatar />
      </SlTooltip>
    </>
  );
};

Removing Arrows

You can control the size of tooltip arrows by overriding the --sl-tooltip-arrow-size design token. To remove them, set the value to 0 as shown below.

Note: Tooltips without arrows are not the standard tooltip pattern in our Design System, and there is no Figma component for this option. Please check with the design team before using this option.

No Arrow

<sl-tooltip content="This is a tooltip" style="--sl-tooltip-arrow-size: 0;">
  <sl-button>No Arrow</sl-button>
</sl-tooltip>

sl-tooltip content="This is a tooltip" style="--sl-tooltip-arrow-size: 0;"
  sl-button No Arrow

import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const App = () => (
  <div style={{ '--sl-tooltip-arrow-size': '0' }}>
    <SlTooltip content="This is a tooltip">
      <SlButton>Above</SlButton>
    </SlTooltip>

    <SlTooltip content="This is a tooltip" placement="bottom">
      <SlButton>Below</SlButton>
    </SlTooltip>
  </div>
);

HTML in Tooltips

Use the content slot to create tooltips with HTML content. Tooltips are designed only for text and presentational elements. Avoid placing interactive content, such as buttons, links, and form controls, in a tooltip.

I’m not just a tooltip, I’m a tooltip with HTML!

Hover me

<sl-tooltip>
  <div slot="content">I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!</div>

  <sl-button>Hover me</sl-button>
</sl-tooltip>

sl-tooltip
  div slot="content"
    | I'm not
    strong
      | just
    |  a tooltip, I'm a
    em
      | tooltip
    |  with HTML!
  sl-button
    | Hover me

import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const App = () => (
  <SlTooltip>
    <div slot="content">
      I'm not <strong>just</strong> a tooltip, I'm a <em>tooltip</em> with HTML!
    </div>

    <SlButton>Hover Me</SlButton>
  </SlTooltip>
);

Setting a Maximum Width

Use the --max-width custom property to change the width the tooltip can grow to before wrapping occurs.

Note: The default max-width for Design System tooltips is 240px (15rem). Please check with the design team before using this option to override this max-width setting.

Hover me

<sl-tooltip style="--max-width: 80px;" content="This tooltip will wrap after only 80 pixels.">
  <sl-button>Hover me</sl-button>
</sl-tooltip>

sl-tooltip style="--max-width: 80px;" content="This tooltip will wrap after only 80 pixels."
  sl-button Hover me

import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const App = () => (
  <SlTooltip style={{ '--max-width': '80px' }} content="This tooltip will wrap after only 80 pixels.">
    <SlButton>Hover Me</SlButton>
  </SlTooltip>
);

Hoisting

Tooltips will be clipped if they’re inside a container that has overflow: auto|hidden|scroll. The hoist attribute forces the tooltip to use a fixed positioning strategy, allowing it to break out of the container. In this case, the tooltip will be positioned relative to its containing block, which is usually the viewport unless an ancestor uses a transform, perspective, or filter. Refer to this page for more details.

<div class="tooltip-hoist">
  <sl-tooltip content="This is a tooltip">
    <sl-button>No Hoist</sl-button>
  </sl-tooltip>

  <sl-tooltip content="This is a tooltip" hoist>
    <sl-button>Hoist</sl-button>
  </sl-tooltip>
</div>

<style>
  .tooltip-hoist {
    position: relative;
    border: solid 2px var(--sl-panel-border-color);
    overflow: hidden;
    padding: var(--sl-spacing-medium);
  }
</style>

div.tooltip-hoist
  sl-tooltip content="This is a tooltip"
    sl-button No Hoist
  sl-tooltip content="This is a tooltip" hoist="true"
    sl-button Hoist

css:
  .tooltip-hoist {
    position: relative;
    border: solid 2px var(--sl-panel-border-color);
    overflow: hidden;
    padding: var(--sl-spacing-medium);
  }

import SlButton from '@teamshares/shoelace/dist/react/button';
import SlTooltip from '@teamshares/shoelace/dist/react/tooltip';

const css = `
  .tooltip-hoist {
    border: solid 2px var(--sl-panel-border-color);
    overflow: hidden;
    padding: var(--sl-spacing-medium);
    position: relative;
  }
`;

const App = () => (
  <>
    <div class="tooltip-hoist">
      <SlTooltip content="This is a tooltip">
        <SlButton>No Hoist</SlButton>
      </SlTooltip>

      <SlTooltip content="This is a tooltip" hoist>
        <SlButton>Hoist</SlButton>
      </SlTooltip>
    </div>

    <style>{css}</style>
  </>
);

Usage guidelines

Tooltip content should be additional or supplemental. Don’t put essential information in a tooltip.
Keep the content simple — ideally just one or two words or a short phrase. If using sentences, try to keep below 2 sentences or 3 lines of text at maximum.
Tooltips should not contain interactive elements like buttons or links or include elements like imagery.

Importing

If you’re using the autoloader or the traditional loader, you can ignore this section. Otherwise, feel free to use any of the following snippets to cherry pick this component.

Script

Import

Bundler

React

To import this component from the CDN using a script tag:

<script type="module" src="https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/tooltip/tooltip.js"></script>

To import this component from the CDN using a JavaScript import:

import 'https://cdn.jsdelivr.net/npm/@shoelace-style/shoelace@2.1.0/cdn/components/tooltip/tooltip.js';

To import this component using a bundler:

import '@shoelace-style/shoelace/dist/components/tooltip/tooltip.js';

To import this component as a React component:

import SlTooltip from '@shoelace-style/shoelace/dist/react/tooltip';

Slots

Name	Description
(default)	The tooltip’s target element. Avoid slotting in more than one element, as subsequent ones will be ignored.
`content`	The content to render in the tooltip. Alternatively, you can use the `content` attribute.

Learn more about using slots.

Properties

Scroll right to see the entire table

Name	Description	Type	Default
`content`	The tooltip’s content. If you need to display HTML, use the `content` slot instead.	`string`	`''`
`placement`	The preferred placement of the tooltip. Note that the actual placement may vary as needed to keep the tooltip inside of the viewport.	`'top' \| 'top-start' \| 'top-end' \| 'right' \| 'right-start' \| 'right-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end'`	`'top'`
`disabled`	Disables the tooltip so it won’t show when triggered.	`boolean`	`false`
`distance`	The distance in pixels from which to offset the tooltip away from its target.	`number`	`8`
`open`	Indicates whether or not the tooltip is open. You can use this in lieu of the show/hide methods.	`boolean`	`false`
`skidding`	The distance in pixels from which to offset the tooltip along its target.	`number`	`0`
`trigger`	Controls how the tooltip is activated. Possible options include `click`, `hover`, `focus`, and `manual`. Multiple options can be passed by separating them with a space. When manual is used, the tooltip must be activated programmatically.	`string`	`'hover focus'`
`hoist`	Enable this option to prevent the tooltip from being clipped when the component is placed inside a container with `overflow: auto\|hidden\|scroll`. Hoisting uses a fixed positioning strategy that works in many, but not all, scenarios.	`boolean`	`false`
`updateComplete`	A read-only promise that resolves when the component has finished updating.

Learn more about attributes and properties.

Events

Name	React Event	Description	Event Detail
`sl-show`	`onSlShow`	Emitted when the tooltip begins to show.	-
`sl-after-show`	`onSlAfterShow`	Emitted after the tooltip has shown and all animations are complete.	-
`sl-hide`	`onSlHide`	Emitted when the tooltip begins to hide.	-
`sl-after-hide`	`onSlAfterHide`	Emitted after the tooltip has hidden and all animations are complete.	-

Learn more about events.

Methods

Name	Description	Arguments
`show()`	Shows the tooltip.	-
`hide()`	Hides the tooltip	-

Learn more about methods.

Custom Properties

Name	Description	Default
`--max-width`	The maximum width of the tooltip before its content will wrap.
`--hide-delay`	The amount of time to wait before hiding the tooltip when hovering.
`--show-delay`	The amount of time to wait before showing the tooltip when hovering.

Learn more about customizing CSS custom properties.

Parts

Name	Description
`base`	The component’s base wrapper, an `<sl-popup>` element.
`base__popup`	The popup’s exported `popup` part. Use this to target the tooltip’s popup container.
`base__arrow`	The popup’s exported `arrow` part. Use this to target the tooltip’s arrow.
`body`	The tooltip’s body where its content is rendered.

Learn more about customizing CSS parts.

Animations

Name	Description
`tooltip.show`	The animation to use when showing the tooltip.
`tooltip.hide`	The animation to use when hiding the tooltip.

Learn more about customizing animations.

Dependencies

This component automatically imports the following dependencies.

<sl-popup>

Examples

Basic Tooltip

Placement

Click Trigger

Manual Trigger

Removing Arrows

HTML in Tooltips

Setting a Maximum Width

Hoisting

Usage guidelines

Importing

Slots

Properties

Events

Methods

Custom Properties

Parts

Animations

Dependencies