---
title: "Track and update visited annotation states | Geosplats sdk"
description: "Mark annotations as visited and update pin icons at runtime."
---
> 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.
# Track and update visited annotation states
This example demonstrates how to use the `SplatAnnotation` runtime methods `setColor()`, `setIcon()`, and event listeners to track user engagement and mark houses as visited across a 6-house residential development.
### 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: [-74.42418, 40.77947],
zoom: 18.2,
pitch: 52,
bearing: -30,
});
let splatModel;
map.on("load", () => {
splatModel = new SplatModel({
model: "YOUR_MAPTILER_SPLAT_MODEL_ID_HERE",
revealParams: { enabled: true },
});
map.addSplatModel(splatModel);
});
const VISITED_COLOR = "#e69439";
const visitedSet = new Set();
const annotationsList = [];
const houseConfigs = [
{
id: "house-1",
pos: { x: 0.05, z: -0.58 },
icon: "🏡",
label: "House 1",
popup:
"
🏡 House 1
Two-story colonial with private driveway and landscaped lawn.
```
## Listening to annotation events
The GeoSplats SDK provides three key annotation lifecycle events:
- `"annotation:click"`: Fires when the user clicks a pin, right before its popup begins to open.
- `"annotation:active"`: Fires when the popup opens on screen.
- `"annotation:inactive"`: Fires when the popup closes (via the close button, clicking the map, or opening another popup).
Every event delivers the affected `annotation` handle in its payload.
## Updating pin colors dynamically
When a user clicks a house annotation, call `annotation.setColor()` to change its background fill immediately to an in-progress color:
```js
const VISITED_COLOR = "#e69439";
map.on("splatmodel:annotation:click", ({ annotation }) => {
annotation.setColor(VISITED_COLOR);
});
```
The pin animates smoothly and maintains its new color even when the camera moves.
## Changing icons when popups close
When the user finishes reading a popup and closes it, the `"annotation:inactive"` event fires. Use `annotation.setIcon()` to replace the pin’s house icon with a completion badge like a checkmark:
```js
map.on("splatmodel:annotation:inactive", ({ annotation }) => {
annotation.setIcon("✔️");
});
```
The pin automatically recalculates its geometry and resizes with a brief squash-and-stretch animation.
## Resetting annotation properties
Calling `annotation.setColor(undefined)` removes the custom color and restores the default MapTiler blue theme:
```js
// Reset pin to default theme
annotation.setColor(undefined);
// Restore original icon from custom data
const data = annotation.getData();
if (data?.defaultIcon) {
annotation.setIcon(data.defaultIcon);
}
```
## Learn more
Check out the [MapTiler GeoSplats SDK reference](https://docs.maptiler.com/geosplats-sdk/api) to learn more about the `SplatAnnotation` API and event parameters.
## 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.
### [Guided tour with annotations](https://docs.maptiler.com/geosplats-sdk/examples/annotation-guided-tour/)
Examples
Guide users through model annotations with next and previous buttons.
### [Filter annotations by category](https://docs.maptiler.com/geosplats-sdk/examples/filter-annotations/)
Examples
Filter annotations by category using visibility toggle or color dimming.