# Scroll Hotspot Tour

> A scroll-driven visual story that travels through one large image, flows between chapters and connects every event to its location with an accurate numbered timeline.

Canonical: https://gsapvault.com/effects/scroll-hotspot-tour
Live demo: https://gsapvault.com/demos/scroll-hotspot-tour/index.html

| Property | Value |
|----------|-------|
| Type | effect |
| Tier | paid |
| Price | £5 |
| Difficulty | advanced |
| Plugins | ScrollTrigger |
| Techniques | scroll-scrub, image-hotspots, guided-camera, sticky-scrollytelling, svg-connector, chapter-navigation, responsive-layout, reduced-motion |
| Uses Lenis | No |

## Lighthouse, as measured

Google Lighthouse on the demo, 15 September 2026. A measurement of the demo as shipped, not a promise for your page.

| Category | Score |
|----------|-------|
| Accessibility | 100 |
| Best practices | 100 |

No performance score is published: it depends on the deployment (server compression, caching, CDN, connection and device) rather than on the code, so measure it where it will live.

## Overview

Lead a visitor around one large photograph, plan or illustration without asking them to hunt for controls. Vertical scroll becomes a paced camera path: the scene pans and subtly changes scale between authored points while flowing continuously into the next chapter.

The active marker stays physically attached to its card through a live routed connector, even while the camera is moving. A compact chapter rail mirrors the same progress and doubles as keyboard-operable jump navigation.

The mobile path brings every subject above a docked annotation instead of covering the photograph. Reduced-motion and no-JavaScript visitors get the complete overview and every annotation in ordinary document flow.

## Features

- Continuous scroll-scrubbed camera travel between percentage-positioned image hotspots
- Authored focal composition places each subject opposite its annotation rather than merely centring every point
- A small depth swell between stops makes the route feel spatial while every chapter settles crisply
- Direction-aware annotation handoffs and an active marker pulse at each chapter boundary
- Live SVG connector redraws throughout camera travel and terminates at the nearest card edge
- Chapter rail shows total progress and provides mouse, touch and keyboard jump navigation
- Responsive camera targets keep mobile subjects clear of the docked annotation card
- Native scrolling works with the product iframe's wheel handoff and does not create a second smooth-scroll owner
- Reduced-motion and no-JavaScript fallbacks show the full scene and all annotation content
- Independent instances with complete ScrollTrigger, observer, listener, animation and state teardown

## Use Cases

- Architecture and property stories that guide viewers through materials, rooms or renovation details
- Product launches that need an authored feature tour through one hero photograph or technical cutaway
- Museum and editorial features where a picture should unfold as a short scroll narrative
- Travel, venue and campus pages that turn one annotated image into a guided route
- Portfolio case studies that need a more directed alternative to click-only image hotspots

## Vibe-Code Ready Setup

This effect includes `START-HERE-AI.md`, a product-specific copy-paste setup prompt for Cursor, Claude Code, ChatGPT, GitHub Copilot, Windsurf, and other coding assistants. It tells the assistant to inspect the existing stack, integrate the supplied files, preserve the design, scope selectors, retain accessibility and responsive behaviour, add framework-appropriate GSAP cleanup, and report what it tested.

[How AI-assisted setup works](https://gsapvault.com/vibe-coding)

## How It Works

Each marker stores its position as percentages of the scene. At refresh time the camera derives a clamped translation for every point, placing the subject in the open part of the frame according to the matching card's declared side. ScrollTrigger scrubs a single progress value across those stops; the renderer eases between neighbouring translations and adds a restrained scale swell halfway through the journey.

When the camera reaches the next numbered stop, the active chapter changes. The timeline fill follows the same continuous progress as the camera. The outgoing and incoming annotations move in the actual scroll direction, the marker sends out a small pulse and the navigation state updates. During every camera frame, the connector measures the active marker and card in viewport coordinates and redraws one curved route between them.

The page uses CSS sticky positioning for the stage and native document scroll for the runway, so ScrollTrigger maps rather than owns scrolling. A reduced-motion media branch creates no ScrollTrigger and exposes the overview plus all cards as a static grid.

## Documentation

How this effect works and how it goes into a page. The reference you use once you own the files (worked examples, events, the programmatic API, the class list) ships with the download.

### Quick Start

**1. Add to your HTML `<head>`:**

_Code snippet omitted: it ships with the download._

**2. Add before closing `</body>`:**

_Code snippet omitted: it ships with the download._

**3. Add a tour:**

_Code snippet omitted: it ships with the download._

Every `data-tour-hotspot` value needs a matching `data-tour-card` and `data-tour-stop`, in the same order. Set the tour's scroll runway in CSS; the demo uses `height: 750svh` on desktop and `690svh` on phones and portrait tablets (up to 900px wide).

### Using It With Your Own Design

**What the effect needs from your markup:** one `[data-scroll-hotspot-tour]`, a sticky `[data-tour-stage]`, a clipped `[data-tour-viewport]`, its movable `[data-tour-scene]` and two or more `[data-tour-hotspot]` markers. Each marker needs a matching `[data-tour-card]`. The connector SVG, path and dot are required on desktop. Stop buttons and the progress element are optional but must keep their hooks if included.

**What is only the demo's styling:** the fictional museum-heist story, museum-atrium photograph, toolbar, numbered marker faces, glass cards, typography, colour palette and chapter rail can all be replaced. The script reads data hooks and the cards' `data-side`, never the decorative classes. Replace the bundled photograph and move the percentage coordinates to its subjects.

**CSS the effect depends on:** the stage must stay sticky within a taller tour wrapper, the viewport must clip, and the scene must be positioned with a stable intrinsic ratio. The script owns the scene transform. Hotspots must remain positioned inside that scene so their transformed rectangles match the image. Cards and the connector must share the viewport's positioning context. Keep the `.has-js` runway gate and the reduced-motion/no-JavaScript static layout so content is never trapped in a sticky page without a working controller.

The camera flows between chapters without reading pauses. A short ending stretch keeps the final chapter visible before the bottom of the page; `endingDuration` controls that space. The numbered timeline travels with it, and chapter buttons land at the corresponding camera point. `holdDuration` is `0`; increase it to add reading pauses. Increase the CSS runway for a slower overall pace.

### Options

| Attribute | Values | Default | Description |
|---|---|---|---|
| `data-scroll-hotspot-tour` | marker | required | Initializes an independent tour |
| `data-scrub` | positive number | `0.7` | Seconds of ScrollTrigger scrub smoothing |
| `data-tour-hotspot` | unique string | required | Links a scene point to its card and stop |
| `data-tour-card` | matching string | required | Annotation activated for that point |
| `data-side` | `left`, `right` | `right` | Places the desktop card and composes the subject opposite it |
| `data-tour-stop` | matching string | optional | Scrolls to the matching chapter |

### Accessibility

- **Keyboard:** each chapter stop is a native button with a visible focus ring. Activating it scrolls to the corresponding point.
- **Touch:** the effect follows ordinary vertical page scrolling and needs no captured gesture or horizontal drag.
- **Reduced motion:** no ScrollTrigger or camera animation is created. The image overview and every annotation are shown in document flow.
- **No JavaScript:** the `.has-js` gate does not create the long runway; the scene and annotations remain visible as static content.
- **Announcements:** the detail region uses `aria-live="polite"`, and inactive cards carry `aria-hidden="true"`.

### Performance Notes

The effect writes one scene transform and one short SVG path per scroll frame. Camera targets are calculated from untransformed layout values, so resizing does not require stored pixel coordinates. A single ResizeObserver debounces refreshes, and the native sticky stage avoids a second pinning system.

### Demo Story

“The seven-minute disappearance” is a fictional heist, using an architectural photograph as its setting. The events and roles are invented; the photograph does not document a theft. Replace the four chapters, times and hotspot coordinates to retell your own event.

### Image Credit

The demo uses an art-directed derivative of an architectural atrium photograph on Unsplash under the Unsplash licence. The shipped 2400 × 3609 WebP preserves the full-height view, with colour grading and compression. The larger scene gives the camera several gallery levels to explore. Replace it with your own image and preserve correct intrinsic dimensions.

### Dependencies

**Required:**

- GSAP 3.12+ (the demo is pinned to GSAP 3.15.0)
- ScrollTrigger

**Optional:**

- None. The effect uses native document scrolling and does not create Lenis.

## What You Get

- `index.html`: working demo page
- `assets/script.js`: commented, readable source
- `assets/style.css`: effect styles
- `README.md`: full documentation with examples and framework integration notes
- `START-HERE-AI.md`: product-specific copy-paste prompt for AI-assisted setup
- `LICENSE.txt`: standard license terms
- Lifetime updates: re-download anytime from your library

## Get the Code

This is a premium effect. The standard license costs £5 one-time and covers unlimited personal and commercial projects with no attribution required for our code. Bundled third-party assets retain their own licences and attribution requirements. The only restrictions: no redistribution of the code itself and no competing effect libraries.

- [Buy Scroll Hotspot Tour](https://gsapvault.com/effects/scroll-hotspot-tour)
- [The Vault (£99 one-time, best value): every collection in the Vault library, plus future items added to those collections](https://gsapvault.com/effects)

## Judge the Code Quality First

These related effects are free with complete source published, written to the same production standard (cleanup functions, reduced-motion support, framework-agnostic):

- [Scroll Progress Indicator](https://gsapvault.com/effects/scroll-progress.md): A precise GSAP reading-progress indicator in four shapes: a top bar, an SVG ring, a side rail, and a numeric percentage.
- [CSS Scroll Reveal](https://gsapvault.com/effects/css-scroll-reveal.md): Native CSS scroll-driven reveals for crisp fade, slide, and scale entrances with accessible static fallbacks and no animation JavaScript.
- [Parallax Hero](https://gsapvault.com/effects/parallax-hero.md): A pinned hero that pulls its layers into depth from one scrubbed ScrollTrigger: a headline sandwiched inside the stack, ridges or photographs climbing over it, and a sun that sets behind the far layer.

---

From [GSAP Vault](https://gsapvault.com): production-ready GSAP animation effects. Full catalog for agents: https://gsapvault.com/llms-full.txt