Change map basemap

This example demonstrates how to dynamically change the underlying basemap using the setBasemap() method while ensuring that your splats models remain correctly positioned and visible in the 3D scene.

One of the key strengths of the MapTiler GeoSplats SDK is its ability to handle complex 3D assets, such as splats, regardless of the base map style. Whether you switch from a satellite view to a minimalist base style, your high-fidelity 3D models stay in place, perfectly aligned with the geographic coordinates.


npm install --save @maptiler/geosplats

main.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.42420, 40.77946],
  zoom: 17.94,
  basemap: "hybrid-v4"
});

map.on("load", () => {
  const splatModel = new SplatModel({
    model: "YOUR_MAPTILER_SPLAT_MODEL_ID_HERE",
  });
  map.addSplatModel(splatModel);

  const styleSelect = document.getElementById("style-select");
  styleSelect.addEventListener("change", (e) => {
    const selectedStyle = e.target.value;
    map.setBasemap(selectedStyle);
  });
});

index.html

<!DOCTYPE html>
<html lang="en">

<head>
  <meta charset="UTF-8">
  <title>Change Map Basemap</title>
  <link rel="stylesheet" href="./style.css">
</head>

<body>
  <div id="map"></div>
  <div id="ui">
    <label for="style-select"><strong>Map Style:</strong></label><br>
    <select id="style-select">
      <option value="satellite-v4">Satellite</option>
      <option value="streets-v4">Streets</option>
      <option value="hybrid-v4" selected>Hybrid</option>
      <option value="dataviz-v4">Dataviz</option>
      <option value="base-v4">Base</option>
    </select>
  </div>
  <script type="module" src="./main.js"></script>
</body>

</html>

style.css

body {
  font-family: Inter, sans-serif;
  margin: 0;
  overflow: hidden;
}

#map {
  width: 100%;
  height: 100vh;
}

#ui {
  position: absolute;
  top: 10px;
  left: 10px;
  background: rgba(255, 255, 255, 0.9);
  padding: 10px;
  border-radius: 4px;
  box-shadow: 0 1px 4px rgba(0, 0, 0, 0.3);
}

select {
  padding: 5px;
  font-size: 14px;
  margin-top: 5px;
}

<!doctype html>
<html lang="en">

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Change Map Basemap</title>
  <link rel="stylesheet"
    href="https://cdn.maptiler.com/maptiler-geosplats/v1.0.9/maptiler-geosplats.css">
  <style>
    body {
      font-family: Inter, sans-serif;
      margin: 0;
      overflow: hidden;
    }

    #map {
      width: 100%;
      height: 100vh;
    }

    #ui {
      position: absolute;
      top: 10px;
      left: 10px;
      background: rgba(255, 255, 255, 0.9);
      padding: 10px;
      border-radius: 4px;
      box-shadow: 0 1px 4px rgba(0, 0, 0, 0.3);
    }

    select {
      padding: 5px;
      font-size: 14px;
      margin-top: 5px;
    }
  </style>
</head>

<body>
  <div id="map"></div>
  <div id="ui">
    <label for="style-select"><strong>Map Style:</strong></label><br>
    <select id="style-select">
      <option value="satellite-v4">Satellite</option>
      <option value="streets-v4">Streets</option>
      <option value="hybrid-v4" selected>Hybrid</option>
      <option value="dataviz-v4">Dataviz</option>
      <option value="base-v4">Base</option>
    </select>
  </div>
  <script type="module">
    import { SplatModel, Map, config } from "https://cdn.maptiler.com/maptiler-geosplats/v1.0.9/maptiler-geosplats.mjs";;

    config.apiKey = 'YOUR_MAPTILER_API_KEY_HERE';
    const map = new Map({
      apiKey: config.apiKey,
      container: "map",
      center: [-74.42420, 40.77946],
      zoom: 17.94,
      basemap: "hybrid-v4"
    });

    map.on("load", () => {
      const splatModel = new SplatModel({
        model: "YOUR_MAPTILER_SPLAT_MODEL_ID_HERE",
      });
      map.addSplatModel(splatModel);

      const styleSelect = document.getElementById("style-select");
      styleSelect.addEventListener("change", (e) => {
        const selectedStyle = e.target.value;
        map.setBasemap(selectedStyle);
      });
    });
  </script>
</body>

</html>

Learn more

Check out the MapTiler GeoSplats SDK JS reference

Change map basemap

main.js

index.html

style.css

Learn more

Add splat model

Edit model in custom editor

Capture events

Opacity and visibility

Change map basemap

NPM module setup

main.js

index.html

style.css

Basic JavaScript setup

Learn more

Related examples

Add splat model

Edit model in custom editor

Capture events

Opacity and visibility