Join us online - 19th of November
Save your spot
For AI agents: a documentation index is available at /llms.txt. Markdown versions of all pages are available by appending .md to any URL.

How to add annotations to a splat model

This example demonstrates how to create interactive annotations on a 3D Gaussian splat model using the MapTiler GeoSplats SDK. Annotations are labelled pins attached to a model that can display HTML popups when clicked.

NPM module setup


npm install --save @maptiler/geosplats
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);
});

map.on("splatmodel:load", () => {
  splatModel.addAnnotation({
    pos: { x: -0.4, z: -0.2 },
    icon: "๐Ÿ–๏ธ",
    label: "Sun Pool",
    popup: "<h3>๐Ÿ–๏ธ Sun Pool</h3><p>Outdoor pool with a 24h bar.</p>",
  });

  splatModel.addAnnotation({
    pos: { x: -0.06, z: -0.26, y: 0.001 },
    icon: "๐Ÿข",
    label: "Main Entrance",
    color: "#2bb673",
    popup: "<h3>๐Ÿข Main Entrance</h3><p>Main hotel lobby, reception, and guest check-in.</p>",
  });

  splatModel.addAnnotation({
    pos: { x: 0.6, z: 0.46 },
    icon: "๐ŸŽพ",
    label: "Tennis Courts",
    popup: "<h3>๐ŸŽพ Tennis Courts</h3><p>10 championship courts with floodlighting.</p>",
  });
});

When to add annotations

The addAnnotation() method on SplatModel is only active once the model is attached and loaded onto the map. Calling splatModel.addAnnotation() before the model loads returns undefined and adds nothing.

Wait for the splatmodel:load event on the map before adding annotations:


map.on("splatmodel:load", () => {
  splatModel.addAnnotation({
    pos: { x: -0.4, z: -0.2 },
    icon: "๐Ÿ–๏ธ",
    label: "Sun Pool",
    popup: "<h3>๐Ÿ–๏ธ Sun Pool</h3><p>Outdoor pool with a 24h bar.</p>",
  });
});

Pin labels and icons

Pins consist of an optional emoji icon (icon) and an optional text label (label). The pin automatically resizes to accommodate its content:

  • Emoji icon: A single emoji shown on the pin.
  • Label: Short text rendered next to the icon in white text with a crisp background.
  • Color: An optional pin fill color (such as hex #2bb673). The default fill is MapTiler blue (#4d7fff).

Keep labels concise. Detailed information, long descriptions, or external links belong in the popup.

Interactive HTML popups

Defining the popup property turns the pin into an interactive card that opens when clicked:

  • HTML content: Accepts any standard HTML string, including headings, paragraphs, and formatted text.
  • Single active popup: Only one popup opens at a time per map. Opening another pin closes any open card.
  • Automatic tracking: The popup tracks the pin across camera pans, rotations, and zoom changes, and hides automatically if the pin moves off-screen.
  • Active state collapsing: When a pinโ€™s popup opens, the pin badge collapses to a circular icon so it does not block the card content.

Learn more

Check out the MapTiler GeoSplats SDK reference to explore the full list of annotation options and event listeners.

How to add a splat model to your map

Add splat model

Examples

Learn how to load a map using the GeoSplats SDK and add a photorealistic splat model. A splat model offer a modern alternative to 3D meshes, perfect for complex scenes.

Position annotations relative to model or geography

Model vs geographic positioning

Examples

Place annotations using model-relative bounding box coordinates or geographic coordinates.

Customize annotation pins and colors

Pin styles and categories

Examples

Style annotations with colors, icons, numbers, and custom popup placement.

Create rich HTML popups in annotations

Rich HTML popups

Examples

Display custom HTML cards in annotation popups with images, tables, and custom widths.

Was this helpful?