Choreograph.js

Choreograph.js is a modern, lightweight library for creating interactive user onboarding tours, product walkthroughs, and automated session replays. It features smart positioning, visual connectors, focus trapping, and a robust session recorder/replayer system.

Features

• 🎯 Smart Spotlight: Highlights elements with a customizable overlay.
• 💬 Adaptive Annotations: Tooltips automatically position themselves to stay in view.
• 🔗 Visual Connectors: Elegant Bézier curves connect annotations to their targets.
• 🔒 Focus Trap: Keeps keyboard navigation within the active step for accessibility.
• 🎥 Session Recording: Record user interactions (clicks, mouse movements) during a tour.
• ⏯️ Session Replay: Replay recorded sessions with a simulated "Ghost Cursor" that adapts to layout changes.
• 🧩 Robust Triggers: Waits for elements to appear and handles dynamic content gracefully.

Installation

via NPM

npm install choreograph.js

via CDN / Script Tag

Include the UMD build in your HTML:

<script src="dist/choreograph.min.js"></script>

Quick Start

1. Initialize the Library

import Choreograph from 'choreograph.js'; // ESM
// or const Choreograph = window.Choreograph; // UMD

const choreo = new Choreograph();

2. Define Your Scenes

A "scene" represents a step in your tour.

const scenes = [
    {
        id: 'step-1',
        selector: '#header-logo',
        annotation: {
            text: 'Welcome! This is our logo.',
            position: 'bottom'
        },
        trigger: {
            type: 'click',
            targetSelector: '#next-button'
        }
    },
    {
        id: 'step-2',
        selector: '.feature-box',
        annotation: {
            text: 'Here is a cool feature.',
            position: 'right'
        },
        trigger: {
            type: 'click',
            targetSelector: '.finish-btn'
        },
        allowInteraction: true // Allow user to click the highlighted element
    }
];

3. Play the Tour

choreo.play(scenes).then(() => {
    console.log('Tour completed!');
});

API Reference

new Choreograph()

Creates a new instance. Automatically initializes the overlay and canvas.

play(scenes)

Starts the tour sequence.

• scenes: Array of Scene objects.
• Returns: A Promise that resolves when the tour finishes.

destroy()

Completely cleans up the instance. Removes the overlay, canvas, event listeners, and stops any active recording or replay.

recorder

Access the built-in session recorder.

• recorder.start(): Start recording user actions.
• recorder.stop(): Stop recording.
• recorder.getEvents(): Get the array of recorded events.

replayer

Access the session replayer.

• replayer.play(events, scenes): Replay a recorded session.
  • events: Array of events from recorder.getEvents().
  • scenes: (Optional) The scenes array used during recording, for context-aware positioning.

Scene Configuration

| Property | Type | Description | |----------|------|-------------| | id | string | Unique identifier for the scene. | | selector | string | CSS selector of the element to highlight. | | annotation | object | Configuration for the tooltip. | | annotation.text | string | Text content of the tooltip. | | annotation.position | string | Preferred position (top, bottom, left, right). | | trigger | object | Event that advances to the next scene. | | trigger.type | string | Event type (e.g., click). | | trigger.targetSelector | string | Selector of the element to wait for the event on. | | allowInteraction | boolean | If true, allows clicks to pass through to the highlighted element. |

Advanced Usage

Session Recording & Replay

Choreograph.js can record the user's journey through the tour and replay it later. This is useful for automated testing or demonstrating flows.

// 1. Start Recording (happens automatically during play(), or manually)
choreo.recorder.start();

// ... user interacts ...

// 2. Stop & Get Events
choreo.recorder.stop();
const events = choreo.recorder.getEvents();

// 3. Replay
// The Ghost Cursor will simulate the user's mouse movements and clicks.
choreo.replayer.play(events, scenes);

Ghost Cursor

You can use the GhostCursor class independently for custom demos.

const cursor = new choreo.GhostCursor();
cursor.moveTo(100, 100);
setTimeout(() => cursor.click(), 1000);

Development

1. Clone the repository
2. Install dependencies: npm install
3. Build the library: npm run build (Outputs to dist/)
4. Run the demo: Open demo/index.html in your browser.

License

MIT