Spotlights

Spotlights are single-element highlights that draw attention to a specific part of the page. Unlike tours (which are multi-step), a spotlight focuses on one element with a darkened backdrop overlay that dims the rest of the page, making the target element visually prominent.

Overview

A spotlight consists of:

• Backdrop overlay -- Dims the entire page except the target element
• Highlighted element -- The target element "pops" through the overlay, appearing brighter and more prominent
• Callout -- A tooltip-style card positioned next to the highlighted element with a title, body, and optional CTA

Spotlights are ideal for:

• Drawing attention to a new feature or button
• Highlighting a changed UI element after a product update
• Focusing the user on a specific action they need to take
• Announcing a promotion or offer attached to a specific element

Creating a Spotlight

Via the Admin Panel

1. Navigate to Content > Spotlights and click Create Spotlight.
2. Click on the target element using the visual element selector.
3. Write the callout title and body content.
4. Configure trigger, audience, and scheduling rules.
5. 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": "spotlight",
  "name": "New Export Button",
  "selector": "[data-spotlight='export-btn']",
  "position": "bottom",
  "title": "New: Export to PDF",
  "body": "<p>You can now export your reports as PDF files. Click here to try it.</p>",
  "cta": { "text": "Try It", "action": "click_target" },
  "dismiss_text": "Got It",
  "trigger": { "trigger_type": "first_visit" },
  "audience": {
    "rules": [
      { "attribute": "plan", "operator": "in", "values": ["pro", "enterprise"] }
    ]
  }
}

Configuration

Field	Type	Required	Description
name	string	Yes	Internal name for the spotlight (not shown to users)
selector	string	Yes	CSS selector targeting the DOM element to highlight
position	string	No	Callout position relative to the target: top, bottom, left, right, auto (default: auto)
title	string	Yes	Callout heading text
body	string	No	Callout body content (supports safe HTML)
cta	object	No	Call-to-action button configuration
dismiss_text	string	No	Text for the dismiss button (default: "Got It")
media	object	No	Embedded image or video in the callout
backdrop_click_dismisses	boolean	No	Whether clicking the backdrop overlay dismisses the spotlight (default: true)
trigger	object	No	When to show the spotlight
audience	object	No	Who should see the spotlight

Backdrop Overlay

The backdrop overlay covers the entire viewport with a semi-transparent dark layer. The target element is "cut out" of the overlay, appearing at full brightness.

The overlay colour is controlled by the --spot-overlay-bg theme variable:

Spotlight.init({
  apiKey: 'spot_live_abc123',
  theme: {
    '--spot-overlay-bg': 'rgba(0, 0, 0, 0.6)',
  },
});

By default, clicking anywhere on the backdrop dismisses the spotlight. Set backdrop_click_dismisses: false to require the user to click the dismiss button or CTA.

TIP

The backdrop overlay is rendered inside the Shadow DOM and does not affect your page's scroll position or interact with your page's event listeners. The target element remains fully interactive -- the user can click it, hover over it, and tab to it normally.

Callout Positioning

The callout card is positioned using @floating-ui/dom with automatic overflow detection. If the preferred position would cause the callout to extend beyond the viewport, it flips to the opposite side or shifts along the axis to fit.

{
  "position": "right"
}

Position	Behaviour
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)

CTA Actions

The optional call-to-action button supports the same action types as tour steps:

Action	Description
dismiss	Close the spotlight (default)
click_target	Simulate a click on the highlighted element, then dismiss
url	Navigate to a URL

{
  "cta": {
    "text": "Try It Now",
    "action": "click_target"
  }
}

Missing Target Behaviour

If the target element is not found:

1. The spotlight does not render. No backdrop, no callout, no error.
2. A targeting.element_not_found event is sent to the backend.
3. The SDK retries on subsequent DOM mutations (the element may appear later in SPA navigation).
4. After 3 retries, a targeting.permanently_missing event is sent and the spotlight is abandoned for this page load.

Programmatic Control

Spotlights fire on the trigger + audience rules attached in the admin panel. Hook content:dismiss to react when one closes:

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

Spotlights vs Tours

Feature	Spotlight	Tour
Elements highlighted	1	Multiple (sequential)
Backdrop overlay	Yes	Optional per step
Progress indicator	No	Yes
Navigation controls	Dismiss only	Next, Previous, Skip
User progress tracked	Viewed/dismissed	Per-step completion

Use a spotlight when you want to draw attention to a single element. Use a tour when you need to walk the user through a sequence of elements.