---
title: "Create a guided tour with annotations | Geosplats sdk"
description: "Guide users through model annotations with next and previous buttons."
---
> For AI agents: a documentation index is available at [/llms.txt](https://docs.maptiler.com/llms.txt). Markdown versions of all pages are available by appending .md to any URL.
# Create a guided tour with annotations
This example demonstrates how to build a guided tour by controlling annotations programmatically with `openPopup()` and `closePopup()`.
### NPM module setup
```bash
npm install --save @maptiler/geosplats
```
#### main.js
```js
import { SplatModel, Map, config } from "@maptiler/geosplats";
import "@maptiler/geosplats/dist/maptiler-geosplats.css";
config.apiKey = "YOUR_MAPTILER_API_KEY_HERE";
const map = new Map({
apiKey: config.apiKey,
container: "map",
center: [-80.27822, 25.74077],
zoom: 17.5,
pitch: 50,
bearing: -15,
});
let splatModel;
map.on("load", () => {
splatModel = new SplatModel({
model: "YOUR_MAPTILER_SPLAT_MODEL_ID_HERE",
revealParams: { enabled: true },
});
map.addSplatModel(splatModel);
});
const tour = [];
let currentStep = 0;
function goTo(index) {
if (!tour.length) return;
currentStep = (index + tour.length) % tour.length;
const indicator = document.getElementById("stepIndicator");
if (indicator) {
indicator.textContent = `Step ${currentStep + 1} of ${tour.length}`;
}
tour[currentStep].openPopup();
}
map.on("splatmodel:load", () => {
const a1 = splatModel.addAnnotation({
pos: { x: -0.06, z: -0.26 },
icon: "🏢",
label: "1. Main Lobby",
popup: "
```
## Opening popups programmatically
While popups typically open on user clicks, you can trigger them directly in JavaScript using the `SplatAnnotation` instance handle.
Calling `annotation.openPopup()` opens the annotation’s popup and automatically closes whichever popup was previously open:
```js
const tour = []; // SplatAnnotation handles
function goTo(stepIndex) {
tour[stepIndex].openPopup();
}
```
Unlike user clicks, `openPopup()` does not fire `"annotation:click"`, but it fires `"annotation:active"` on the model and `"splatmodel:annotation:active"` on the map.
## Navigating between tour steps
Store the returned `SplatAnnotation` handles in an array when adding annotations during `splatmodel:load`. You can then step forward or backward using external UI buttons:
```js
let currentStep = 0;
document.getElementById("nextBtn").addEventListener("click", () => {
currentStep = (currentStep + 1) % tour.length;
tour[currentStep].openPopup();
});
```
When a popup opens, the active pin bounces and a pulse ring ripples across the model surface, directing the viewer’s attention to the active point of interest.
## Keyboard shortcuts and escape handling
You can close any open popup programmatically with `closePopup()`. This makes it simple to bind keyboard shortcuts like `Escape` or the left and right arrow keys:
```js
document.addEventListener("keydown", (event) => {
if (event.key === "Escape") {
tour[currentStep]?.closePopup();
}
});
```
## Learn more
Check out the [MapTiler GeoSplats SDK reference](https://docs.maptiler.com/geosplats-sdk/api) to explore the `SplatAnnotation` interface.
## Related examples
### [Add annotations](https://docs.maptiler.com/geosplats-sdk/examples/add-annotations/)
Examples
Add interactive labelled pins and popups to a splat model.
### [Pin styles and categories](https://docs.maptiler.com/geosplats-sdk/examples/annotation-styles/)
Examples
Style annotations with colors, icons, numbers, and custom popup placement.
### [Filter annotations by category](https://docs.maptiler.com/geosplats-sdk/examples/filter-annotations/)
Examples
Filter annotations by category using visibility toggle or color dimming.
### [Sync annotations with sidebar](https://docs.maptiler.com/geosplats-sdk/examples/sync-annotations-sidebar/)
Examples
Connect 3D model annotations bidirectionally with an external sidebar list.