Tooltips

Tooltips provide contextual help attached to specific elements on the page. Unlike spotlights (which demand attention with a backdrop overlay) or tours (which guide through a sequence), tooltips are passive -- they appear when a user hovers over or focuses on a target element, providing helpful information without interrupting the user's workflow.

Overview

A tooltip consists of:

• Target element -- The DOM element the tooltip is attached to
• Content card -- A small popover with title, body text, and optional media
• Trigger interaction -- How the tooltip appears (hover, click, or always visible)

Tooltips are ideal for:

• Explaining what a button or feature does
• Providing additional context for form fields
• Showing keyboard shortcut hints
• Displaying brief help text for icons or labels
• Contextual tips that appear when the user needs them

Creating a Tooltip

Via the Admin Panel

1. Navigate to Content > Tooltips and click Create Tooltip.
2. Click on the target element using the visual element selector.
3. Write the tooltip title and body content.
4. Choose the activation method (hover, click, or always visible).
5. Configure audience and page targeting.
6. Click Publish.

Via the API

All non-tour content shares one admin endpoint — POST /v1/admin/content — discriminated by content_type.

POST /v1/admin/content
Content-Type: application/json
X-Api-Key: sk_live_...

{
  "content_type": "tooltip",
  "name": "Export Format Help",
  "selector": "[data-spotlight='format-selector']",
  "position": "top",
  "activation": "hover",
  "title": "Export Formats",
  "body": "<p><b>CSV</b> works with Excel and Google Sheets.<br/><b>PDF</b> is best for sharing and printing.</p>",
  "trigger": { "trigger_type": "page_load" }
}

Configuration

Field	Type	Required	Description
name	string	Yes	Internal name for the tooltip
selector	string	Yes	CSS selector targeting the DOM element
position	string	No	Tooltip position: top, bottom, left, right, auto (default: auto)
activation	string	No	How the tooltip appears: hover, click, always (default: hover)
title	string	No	Optional heading text
body	string	Yes	Tooltip content (supports safe HTML)
media	object	No	Embedded image or video
show_close	boolean	No	Show a close button (default: false for hover, true for click/always)
max_width	string	No	Maximum width of the tooltip card (default: 320px)
trigger	object	No	When the tooltip becomes available
audience	object	No	Who should see the tooltip

Activation Modes

Hover

The tooltip appears when the user hovers over the target element and disappears when the mouse leaves. A short delay (200ms) prevents the tooltip from flickering on accidental mouse passes.

{ "activation": "hover" }

The tooltip also appears on keyboard focus (focusin) for accessibility, and disappears on focusout.

Click

The tooltip appears when the user clicks the target element and stays visible until dismissed. A close button is shown by default.

{ "activation": "click" }

Always Visible

The tooltip is always visible as long as the target element is in the DOM. Useful for persistent contextual hints that should remain on screen.

{ "activation": "always" }

TIP

"Always visible" tooltips are dismissed by progress tracking -- once a user has seen it, it does not reappear (unless demoMode is enabled). This makes them suitable for first-time help hints.

Positioning

Tooltip positioning uses @floating-ui/dom with automatic flip and shift middleware:

Position	Description
top	Above the target element
bottom	Below the target element
left	To the left of the target element
right	To the right of the target element
auto	Best fit based on available viewport space (default)

If the preferred position would cause the tooltip to overflow the viewport, it automatically flips to the opposite side or shifts along the axis.

Rich Content

Tooltip body content supports safe HTML. The built-in sanitiser allows:

• Text formatting: <b>, <i>, <strong>, <em>, <span>
• Structure: <p>, <br>, <ul>, <ol>, <li>, <h3>, <h4>
• Links: <a href="..." target="_blank">
• Media: <img>, <video>

{
  "body": "<p>Keyboard shortcuts:</p><ul><li><b>/</b> -- Search</li><li><b>?</b> -- Help</li><li><b>Esc</b> -- Close dialog</li></ul>"
}

WARNING

All on* event handler attributes, <script> tags, <iframe> tags, and javascript: URLs are stripped by the sanitiser. Links always receive rel="noopener noreferrer".

Missing Target Behaviour

If the target element is not found in the DOM:

1. The tooltip is not rendered. No error, no blank space.
2. A targeting.element_not_found event is sent to the backend.
3. The SDK retries on subsequent DOM mutations (for SPA element rendering).
4. After 3 retries, the tooltip is abandoned for this page load.

Programmatic Control

Tooltips fire on their activation mode (hover / click / always) plus audience + page-match rules. Hook content:dismiss to react when one closes:

Spotlight.on('content:dismiss', (data) => {
  console.log(`User dismissed content: ${data.contentId}`);
});

Styling

Tooltips inherit all --spot-* theme variables. Key variables for tooltip appearance:

Variable	Effect
--spot-bg	Tooltip background colour
--spot-text	Tooltip text colour
--spot-border	Tooltip border colour
--spot-radius	Tooltip border radius
--spot-shadow	Tooltip box shadow
--spot-font-size-sm	Tooltip body text size
--spot-font-size-base	Tooltip title text size

Tooltips vs Other Content Types

Feature	Tooltip	Spotlight	Hotspot
Backdrop overlay	No	Yes	No
Activation	Hover/click/always	Trigger-based	Click on beacon
Interrupts workflow	No	Yes	No
Persistent indicator	No	No	Yes (beacon)
Ideal for	In-context help	Feature announcements	Discoverable hints