Hotspots

Hotspots are persistent visual indicators attached to specific elements on the page. They appear as a pulsing beacon or help icon, signalling that contextual information is available. When the user clicks the hotspot, a popover card appears with detailed content.

Overview

A hotspot consists of:

• Beacon -- A small pulsing circle or icon positioned on or near the target element
• Popover -- A content card that appears when the user clicks the beacon
• Target element -- The DOM element the hotspot is attached to

Hotspots are ideal for:

• Discoverable in-context help (users explore at their own pace)
• Highlighting new features without interrupting workflow
• Providing supplementary information for complex UI elements
• Progressive disclosure of advanced functionality

Creating a Hotspot

Via the Admin Panel

1. Navigate to Content > Hotspots and click Create Hotspot.
2. Click on the target element using the visual element selector.
3. Choose the beacon variant (pulse or help icon).
4. Write the popover title and body content.
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": "hotspot",
  "name": "Chart Type Selector Help",
  "selector": "[data-spotlight='chart-type']",
  "variant": "pulse",
  "beacon_position": "top-right",
  "popover_position": "right",
  "title": "Chart Types",
  "body": "<p>Choose from bar, line, pie, or area charts. Each type works best for different data patterns.</p>",
  "trigger": { "trigger_type": "page_load" }
}

Configuration

Field	Type	Required	Description
name	string	Yes	Internal name for the hotspot
selector	string	Yes	CSS selector targeting the DOM element
variant	string	No	Beacon style: pulse or help_icon (default: pulse)
beacon_position	string	No	Where the beacon appears on the target element
popover_position	string	No	Popover position: top, bottom, left, right, auto
title	string	No	Popover heading text
body	string	Yes	Popover content (supports safe HTML)
media	object	No	Embedded image or video in the popover
cta	object	No	Call-to-action button in the popover
dismiss_on_click_outside	boolean	No	Close popover when clicking outside it (default: true)
persist_beacon	boolean	No	Keep beacon visible even after the popover has been viewed (default: true)
trigger	object	No	When the hotspot becomes available
audience	object	No	Who should see the hotspot

Beacon Variants

Pulse

A small circle that pulses with a subtle animation, drawing the user's eye without being intrusive. The pulse animation uses the --spot-hotspot-color and --spot-hotspot-size theme variables.

{ "variant": "pulse" }

The default pulse is a 24px circle in the primary colour with a repeating scale animation.

Help Icon

A small question mark icon (?) in a circle. More explicit than the pulse beacon -- clearly communicates that help is available.

{ "variant": "help_icon" }

Beacon Position

The beacon_position field controls where the beacon sits relative to the target element:

Value	Description
top-left	Top-left corner of the target element
top-right	Top-right corner of the target element (default)
bottom-left	Bottom-left corner of the target element
bottom-right	Bottom-right corner of the target element
center	Centered on the target element

The beacon is positioned absolutely relative to the target element using getBoundingClientRect(). On scroll or resize, the beacon position is recalculated.

Popover

When the user clicks the beacon, a popover card appears. The popover supports the same rich content as tooltips and spotlights:

{
  "title": "Advanced Filtering",
  "body": "<p>Use <b>AND</b> and <b>OR</b> operators to combine filters.</p><p>Example: <code>status:active AND region:EU</code></p>",
  "cta": {
    "text": "Learn More",
    "action": "url",
    "url": "https://docs.example.com/filtering"
  }
}

The popover closes when the user:

• Clicks the close button
• Clicks outside the popover (if dismiss_on_click_outside is true)
• Presses Escape

Beacon Persistence

By default, the beacon remains visible even after the user has viewed the popover (persist_beacon: true). This allows users to re-access the help content at any time.

Set persist_beacon: false to hide the beacon after the first interaction. The hotspot's progress state changes to "viewed" and the beacon does not reappear on subsequent visits.

{
  "persist_beacon": false
}

Theming

Hotspot-specific theme variables:

Variable	Default	Description
--spot-hotspot-color	#4f46e5 (light) / #818cf8 (dark)	Beacon colour
--spot-hotspot-size	24px	Beacon diameter

Spotlight.init({
  apiKey: 'spot_live_abc123',
  theme: {
    '--spot-hotspot-color': '#FF6B00',
    '--spot-hotspot-size': '20px',
  },
});

Missing Target Behaviour

If the target element is not found:

1. Neither the beacon nor the popover is rendered.
2. A targeting.element_not_found event is sent to the backend.
3. The SDK retries on subsequent DOM mutations.
4. After 3 retries, the hotspot is abandoned for this page load.

Programmatic Control

Hotspots fire on their trigger + audience rules. Hook content:dismiss to react when the popover closes:

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

Hotspots vs Tooltips

Feature	Hotspot	Tooltip
Visual indicator	Persistent beacon (pulse/icon)	None
Activation	Click on beacon	Hover/click on target element
User discovers it	By seeing the beacon	By hovering over the element
Persists across visits	Configurable	Based on progress tracking
Best for	Discoverable help, new features	In-context explanations