Use <overlay-trigger> when you need multiple interaction types on a single trigger element. This component excels at:

• Hover tooltip + click dialog: Show a tooltip on hover and open a dialog on click
• Multiple related actions: Different overlays for click, hover, and longpress on the same element
• Simplified API: Slot-based approach with automatic content lifecycle management

Don't use <overlay-trigger> when you need:

• Virtual positioning: VirtualTrigger for cursor-based positioning (use <sp-overlay> or imperative API)
• Single interaction only: For one interaction type, <sp-overlay> is simpler
• Fine-grained control: Advanced features like custom focus behavior (use <sp-overlay>)

See the Getting Started Guide for a complete comparison of entry points.

An <overlay-trigger> element supports the delivery of temporary overlay content based on interaction with a persistent trigger element. An element prepared to receive accessible interactions (e.g. an <sp-button>, or <button>, etc.) is addressed to slot="trigger", and the content to display (either via click or hover/focus interactions) is addressed to slot="click-content" or slot="hover-content", respectively. A trigger element can be linked to the delivery of content, intended for a single interaction, or both. Content addressed to slot="hover-content" is made available when the mouse enters or leaves the target element. Keyboard navigation will make this content available when focus enters or leaves the target element. Be thoughtful with what content you address to slot="hover-content", as the content available via "hover" will be transient and non-interactive.

yarn add @spectrum-web-components/overlay

Import the side-effectful registration of <overlay-trigger> via:

import '@spectrum-web-components/overlay/overlay-trigger.js';

The default of <overlay-trigger> will load dependencies in @spectrum-web-components/overlay asynchronously via a dynamic import. In the case that you would like to import those tranverse dependencies statically, import the side effectful registration of <overlay-trigger> as follows:

import '@spectrum-web-components/overlay/sync/overlay-trigger.js';

When looking to leverage the OverlayTrigger base class as a type and/or for extension purposes, do so via:

import { OverlayTrigger } from '@spectrum-web-components/overlay';

In this example, a default <overlay-trigger> manages content that is triggered by "click" and "hover" interactions.

<overlay-trigger placement="top" type="replace">
    <sp-button slot="trigger">Overlay Trigger</sp-button>
    <sp-popover slot="click-content" open>
        <sp-dialog size="s">
            <h2 slot="heading">Click content</h2>
            An &lt;overlay-trigger&gt; can be used to manage either or both of
            the "click" and "hover" content slots that are made available. Here,
            content is only addressed to
            <code>slot="click-content"</code>
            ...
            <sp-button
                slot="button"
                onclick="javascript: this.dispatchEvent(new Event('close', {bubbles: true, composed: true}));"
            >
                I understand
            </sp-button>
        </sp-dialog>
    </sp-popover>
    <sp-tooltip slot="hover-content">Hover content</sp-tooltip>
</overlay-trigger>

When using the placement attribute of an <overlay-trigger> ("top" |"top-start" | "top-end" | "bottom" | "bottom-start" | "bottom-end" | "right" | "right-start" | "right-end" | "left" | "left-start" | "left-end"), you can suggest to the overlay in which direction relative to the trigger that the content should display. When there is adequate room for the content to display in the specified direction, it will do so. When adequate room is not available, the overlaid content will calculate the direction in which it has the most room to be displayed and use that direction.

The type of an Overlay outlines a number of things about the interaction model within which it works:

Note: The type attribute only affects click-triggered overlays. Hover overlays always use hint type behavior, and longpress overlays always use auto type behavior. For more control over hover and longpress overlay types, use <sp-overlay> directly.

One of the key benefits of <overlay-trigger> is supporting multiple interaction types on a single trigger:

<!-- Tooltip on hover, dialog on click -->
<overlay-trigger placement="top">
    <sp-button slot="trigger">Help</sp-button>

    <!-- Shows on hover - always non-interactive (hint type) -->
    <sp-tooltip slot="hover-content">Click for more information</sp-tooltip>

    <!-- Shows on click - interactive (uses type attribute) -->
    <sp-popover slot="click-content">
        <sp-dialog size="s">
            <h2 slot="heading">Help</h2>
            <p>Detailed help content goes here...</p>
            <sp-button
                slot="button"
                onclick="this.dispatchEvent(new Event('close', {bubbles: true}))"
            >
                Got it
            </sp-button>
        </sp-dialog>
    </sp-popover>
</overlay-trigger>

Content in slot="hover-content" is always non-interactive because it uses hint type behavior:

• Cannot contain focusable elements
• Closes when the user interacts with the page
• Best for tooltips and brief informational content

If you need interactive content on hover, use <sp-overlay> with trigger="id@hover" and type="auto" instead.

Common patterns:

Tooltip + Action:

<overlay-trigger>
    <sp-button slot="trigger">Delete</sp-button>
    <sp-tooltip slot="hover-content">Delete item</sp-tooltip>
    <sp-popover slot="click-content">
        <sp-dialog>
            <h2 slot="heading">Confirm deletion</h2>
            <p>Are you sure?</p>
        </sp-dialog>
    </sp-popover>
</overlay-trigger>

Longpress + Hover:

<overlay-trigger>
    <sp-action-button slot="trigger" hold-affordance>
        <sp-icon-settings slot="icon"></sp-icon-settings>
    </sp-action-button>
    <sp-tooltip slot="hover-content">Hold for more options</sp-tooltip>
    <sp-popover slot="longpress-content">
        <sp-menu>
            <sp-menu-item>Option 1</sp-menu-item>
            <sp-menu-item>Option 2</sp-menu-item>
        </sp-menu>
    </sp-popover>
</overlay-trigger>

All three interactions:

<overlay-trigger>
    <sp-button slot="trigger">Actions</sp-button>
    <sp-tooltip slot="hover-content">Quick action menu</sp-tooltip>
    <sp-popover slot="click-content">
        <sp-menu>
            <sp-menu-item>Copy</sp-menu-item>
            <sp-menu-item>Paste</sp-menu-item>
        </sp-menu>
    </sp-popover>
    <sp-popover slot="longpress-content">
        <sp-menu>
            <sp-menu-item>Advanced option 1</sp-menu-item>
            <sp-menu-item>Advanced option 2</sp-menu-item>
        </sp-menu>
    </sp-popover>
</overlay-trigger>

<overlay-trigger type="modal" triggered-by="click">
    <sp-button slot="trigger">Open modal</sp-button>
    <sp-dialog-wrapper
        slot="click-content"
        headline="Signin form"
        dismissable
        underlay
    >
        <p>I am a modal type overlay.</p>
        <sp-field-label>Enter your email</sp-field-label>
        <sp-textfield placeholder="test@gmail.com"></sp-textfield>
        <sp-action-button
            onClick="
                this.dispatchEvent(
                    new Event('close', {
                        bubbles: true,
                        composed: true,
                    })
                );
            "
        >
            Sign in
        </sp-action-button>
    </sp-dialog-wrapper>
</overlay-trigger>

<overlay-trigger type="page" triggered-by="click">
    <sp-button slot="trigger">Open page</sp-button>
    <sp-dialog-wrapper
        slot="click-content"
        headline="Full screen menu"
        mode="fullscreenTakeover"
        cancel-label="Close"
    >
        <p>I am a page type overlay.</p>
    </sp-dialog-wrapper>
</overlay-trigger>

<overlay-trigger type="hint" triggered-by="hover">
    <sp-button slot="trigger">Open hint</sp-button>
    <sp-tooltip slot="click-content">
        I am a hint type overlay. I am not interactive and will close when the
        user interacts with the page.
    </sp-tooltip>
</overlay-trigger>

<overlay-trigger type="auto" triggered-by="click" placement="bottom">
    <sp-button slot="trigger">Open overlay</sp-button>
    <sp-popover slot="click-content" dialog>
        <p>
            My slider in overlay element:
            <sp-slider label="Slider Label - Editable" editable></sp-slider>
        </p>
    </sp-popover>
</overlay-trigger>

<style>
    .chat-container {
        position: fixed;
        bottom: 1em;
        left: 1em;
    }
</style>
<overlay-trigger type="manual" triggered-by="click">
    <sp-button slot="trigger">Open manual</sp-button>
    <sp-popover slot="click-content" class="chat-container">
        <sp-dialog dismissable>
            <span slot="heading">Chat Window</span>
            <sp-textfield placeholder="Enter your message"></sp-textfield>
            <sp-action-button>Send</sp-action-button>
        </sp-dialog>
    </sp-popover>
</overlay-trigger>

The triggered-by attribute (triggeredBy property) allows you to explicitly declare which types of overlays your implementation will use. This can help optimize performance by avoiding unnecessary DOM operations and preventing race conditions during rendering.

<!-- Only using click and hover overlays -->
<overlay-trigger triggered-by="click hover">
    <sp-button slot="trigger">Click and hover trigger</sp-button>
    <sp-popover slot="click-content" direction="bottom" tip>
        Click content
    </sp-popover>
    <sp-tooltip slot="hover-content">Hover content</sp-tooltip>
</overlay-trigger>

<!-- Only using longpress overlay -->
<overlay-trigger triggered-by="longpress">
    <sp-button slot="trigger">Longpress trigger</sp-button>
    <sp-popover slot="longpress-content" direction="bottom" tip>
        Longpress content
    </sp-popover>
    <div slot="longpress-describedby-descriptor">
        Press and hold to reveal more options
    </div>
</overlay-trigger>

The triggered-by attribute accepts a space-separated string of overlay types:

• click - For click-triggered content
• hover - For hover/focus-triggered content
• longpress - For longpress-triggered content

When not specified, the component will automatically detect which content types are present, but this may result in additional rendering cycles. For optimal performance, especially in applications with many overlay triggers, explicitly declaring the content types you plan to use is recommended.

When using <overlay-trigger>, follow these accessibility guidelines:

The content in slot="trigger" must be "interactive" - able to receive focus and respond to keyboard events. Use:

• <sp-button> or native <button>
• <sp-action-button>
• <a href="#"> (links)
• Other focusable, keyboard-accessible elements

Don't use:

• <div> or <span> without proper ARIA roles and keyboard handlers
• Elements that can't receive focus

Add appropriate ARIA attributes to trigger elements:

<overlay-trigger type="modal">
    <sp-button slot="trigger" aria-haspopup="dialog" aria-expanded="false">
        Open Dialog
    </sp-button>
    <sp-popover slot="click-content">
        <sp-dialog aria-labelledby="dialog-title">
            <h2 id="dialog-title" slot="heading">Dialog Title</h2>
            <p>Dialog content...</p>
        </sp-dialog>
    </sp-popover>
</overlay-trigger>

Recommended attributes:

• aria-haspopup: Indicates the type of overlay ("dialog", "menu", "true")
• aria-expanded: Reflects overlay open/closed state (managed automatically by overlay system)
• aria-labelledby / aria-label: Labels for overlay content

The overlay system handles most keyboard interactions:

• ESC: Closes overlay and returns focus to trigger
• TAB: Navigates within interactive overlays
• Enter/Space: Activates trigger button

For hover tooltips, ensure keyboard users can access the same information:

<!-- Good: Tooltip accessible via focus -->
<overlay-trigger>
    <sp-button slot="trigger">Help</sp-button>
    <sp-tooltip slot="hover-content">
        This tooltip shows on both hover and keyboard focus
    </sp-tooltip>
</overlay-trigger>

Follow these guidelines:

• Use proper heading structure in overlay content
• Provide descriptive labels for all interactive elements
• Ensure error messages in overlays are announced

For more details, see the Accessibility Guide.

Learn more about accessible keyboard interactions at W3C WCAG 2.1 Understanding keyboard.

API