# Image Hotspot Explorer

> A draggable image explorer where selecting a hotspot pans the scene into composition, routes a live connector around the subject and settles a detail card into the clear side of the frame.

Canonical: https://gsapvault.com/effects/image-hotspot-explorer
Live demo: https://gsapvault.com/demos/image-hotspot-explorer/index.html

| Property | Value |
|----------|-------|
| Type | effect |
| Tier | paid |
| Price | £5 |
| Difficulty | advanced |
| Plugins | Core GSAP only |
| Techniques | image-hotspots, drag-to-pan, momentum, collision-aware-popover, svg-connector, magnetic-pointer, keyboard-navigation, touch-gestures, responsive-layout |
| 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

Turn a large photograph, plan or illustration into a guided inspection surface. Visitors can drag the scene freely, then choose a hotspot to bring that feature into a deliberate reading position while its annotation finds the open side of the frame and connects back to the exact point.

The same component works with pointer, touch, keyboard and an external stop index. On narrow screens the annotation docks below the image instead of covering it, while reduced motion keeps every location immediately reachable without animated travel.

## Features

- Camera panning with axis intent, pointer capture, sampled release velocity and bounded momentum
- Hotspot selection automatically composes the subject opposite its annotation card
- Live SVG connector reroutes and redraws as the scene, marker or card moves
- Pointer-proximity magnetism adds tactility without moving the real hit target
- External stop index, hotspot buttons and arrow keys all share one active state
- Resize-safe percentage coordinates work on photographs, plans, maps and diagrams
- Touch gestures preserve vertical page scrolling until horizontal intent is clear
- Mobile annotations dock below the image; reduced motion and no-JavaScript states remain useful
- Independent instances with complete listener, animation, ticker, attribute and inline-style teardown

## Use Cases

- Property and hospitality tours that call out materials, rooms or amenities in one hero photograph
- Product pages explaining features on furniture, vehicles, devices or technical cutaways
- Museums, galleries and editorial stories annotating details without baking labels into an image
- Travel, campus and venue maps where a visitor needs both free exploration and guided stops
- Portfolio case studies that need a more convincing inspection layer than static numbered dots

## 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 hotspot stores its position as percentages of a scene, so the coordinates survive responsive resizing. A small camera model translates the oversized scene inside a clipped viewport and clamps it at every edge. Pointer samples feed a bounded momentum settle on release.

Selecting a point finds the side with more clear space, moves the camera so the subject and card form a readable composition, then draws a routed connector from the marker to the nearest card edge. The route stays accurate when the component changes size, and its line passes behind the selected marker so the number remains clear.

## 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 one explorer:**

_Code snippet omitted: it ships with the download._

Every value used for `data-hotspot`, `data-detail` and `data-explorer-stop` must match. Put the hotspot at a percentage coordinate with `--x` and `--y`; those coordinates remain stable as the component resizes.

### Using It With Your Own Design

**What the effect needs from your markup:** one `[data-hotspot-explorer]`, a clipped `[data-explorer-viewport]`, its movable `[data-explorer-scene]`, and one or more `[data-hotspot]` buttons inside the scene. Each hotspot needs a matching `[data-detail]` article. The connector SVG, path and dot hooks are required on desktop; the external stop buttons and overview button are optional. If an overview button lives outside the component, keep the `data-explorer-overview` hook.

**What is only the demo's styling:** the dining-room palette, toolbar, numbered marker faces, glass annotation card, detail typography and bottom pill index can all be deleted or replaced. The script never reads those visual classes. The bundled photograph is a Pexels derivative used to demonstrate the interaction; replace it and move the four percentage coordinates to match your subject.

**CSS the effect depends on:** keep the viewport clipped and positioned, the scene absolutely positioned and larger than the viewport, and the hotspots absolutely positioned with their percentage coordinates. The script owns the scene's transform. `touch-action: pan-y` is important: it lets a phone visitor scroll the page until their gesture is clearly horizontal. The connector and details must share the explorer's positioning context so the route is measured in one coordinate system. The `hidden` rule for inactive details must remain. Magnetic movement uses `--mx` and `--my` only on the visual marker; do not use those variables as its logical location.

The script adds `.is-focused` to the explorer while a detail is open. The mobile layout uses that state to collapse the empty annotation slot in Overview; all hotspots remain visible in both states.

### Options

| Attribute | Values | Default | Description |
|---|---|---|---|
| `data-hotspot-explorer` | marker | required | Initializes an independent explorer |
| `data-start` | a hotspot id | first hotspot | Detail selected on mount |
| `data-scene-scale` | number above `1` | `1.34` desktop, `1.2` mobile | Oversizes the scene to create panning room |
| `data-hotspot` | unique string | required | Identifies a hotspot and links it to content |
| `data-detail` | matching string | required | Annotation shown for that hotspot |
| `data-explorer-stop` | matching string | optional | External control that selects the same hotspot |

The scene-scale value becomes the CSS custom property `--scene-scale`. Values around `1.2`–`1.5` keep the subject legible while providing useful travel. Larger values behave more like a map viewer and need more deliberate starting coordinates.

### Accessibility

- **Keyboard:** hotspots and stop controls are native buttons. Arrow keys on a focused hotspot move to the previous or next point; Escape returns to the overview.
- **Touch:** a horizontal gesture pans the scene. Vertical intent remains available to the page, and tapping any marker or stop selects it.
- **Reduced motion:** selection and overview moves become immediate, marker magnetism is not initialized, and all content remains operable.
- **No JavaScript:** the image, hotspot buttons and initially unhidden detail remain visible. Nothing essential is pre-hidden by `.has-js`.
- **Labels:** give every hotspot an `aria-label` that names the feature, and keep the detail region's `aria-live="polite"` so its new content is announced without interrupting the visitor.
- **Focus:** preserve a visible `:focus-visible` treatment when reskinning the buttons.

### Performance Notes

The camera only writes one transform. Connector routing reads the active marker and card rectangles while the camera is moving; inactive annotations have no frame cost. Marker magnetism is limited to fine pointers and uses four small transform variables in the supplied demo. The ResizeObserver only recomposes the selected point after the component changes size.

For very large maps, keep the displayed source near the largest size it will render and let an image CDN supply responsive files. This effect is a guided inspection surface, not a tiled geographic map renderer.

### Image Credit

The demo uses an art-directed derivative of [a dining-room photograph on Pexels](https://www.pexels.com/photo/20548025/) under the Pexels licence. The shipped file is resized, colour graded and compressed to WebP. Replace `assets/img/dining-room.webp` with your own image and update the intrinsic dimensions in the markup.

### Dependencies

**Required:**

- GSAP 3.12+ (core only; the demo is pinned to GSAP 3.15.0)

**Optional:**

- None. The effect has no scroll trigger, smooth scrolling or paid-plugin dependency.

## 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 Image Hotspot Explorer](https://gsapvault.com/effects/image-hotspot-explorer)
- [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):

- [Image Clip Reveal](https://gsapvault.com/effects/image-clip-reveal.md): A cinematic image reveal where a directional polygon aperture opens as the photograph settles from a restrained Ken Burns scale and its caption lands.

---

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