While <sp-tooltip> elements are generally fairly innocuous amounts of DOM, it is possible impact performance with too many Tooltips. To support consumers that use lit-html, Spectrum Web Components also proives a directive to improve performance when using many <sp-tooltip> elements.

yarn add @spectrum-web-components/tooltip

Import the tooltip directive as follows:

import { tooltip } from '@spectrum-web-components/tooltip/src/tooltip-directive.js';

The tooltip directive consists of two main parts:

1. A method returning the TemplateResult defining the content of the open overlay:

() => TemplateResult;

2. An optional options object for configuring the tooltip behavior:

{
    open?: boolean; // Whether the Overlay in question should be rendered open.
    triggerInteraction: TriggerInteraction; // 'click' | 'longpress' | 'hover'
    overlayOptions: OverlayOptions;
    insertionOptions?: InsertionOptions;
    variant: 'info' | 'positive' | 'negative';
}

The overlayOptions are leveraged in the same way as outlined here.

The insertionOptions define where in the DOM the Overlay should be inserted:

type InsertionOptions = {
    el: HTMLElement | (() => HTMLElement); // returning a reference to the element the Overlay should be inserted adjacent to
    where: InsertPosition; // 'afterbegin' | 'afterend' | 'beforebegin' | 'beforeend'
};

The tooltip() directive will automatically wrap whatever content you provide in an <sp-tooltip> element. Pass a TemplateResult into the tooltip() directive to have it rendered to the DOM when the associated Tooltip is about to open and then removed after the Tooltip has closed.

<div id="root"></div>

<script type="module">
    import { tooltip } from '@spectrum-web-components/tooltip/src/tooltip-directive.js';
    import { html, render } from 'lit-html';

    const renderOverlayContent = () => html`
        <p>Tooltip content</p>
    `;

    const template = html`
        <sp-button ${tooltip(renderOverlayContent, {
            variant: 'negative'
        })}>Trigger</sp-button>
    `;

    customElements.whenDefined('code-example').then(() => {
        Promise.all([...document.querySelectorAll('code-example')].map(example => example.updateComplete)).then(() => {
            const appRoot = document.querySelector('#root');
            appRoot.innerHTML = '';
            render(template, appRoot);
        });
    });
</script>

The tooltip directive automatically manages accessibility features:

• Tooltips are associated with their trigger elements via aria-describedby
• Content is only rendered when needed, reducing DOM complexity
• Hover and focus interactions are handled automatically
• Keyboard navigation support is built-in

For more information on accessibility, see the Accessibility section of the tooltip component.