Theming the map

The API can switch the map's visual theme at runtime — between the two built-in Mapsted themes and any custom themes configured for the property in the Mapsted Hub / CMS.

Apply a theme

setTheme() accepts the built-in aliases 'light' and 'dark', or any literal theme id returned by getThemes(). It resolves to the applied Theme object.

import { setTheme } from '@mapsted/maps-js-api';

// Built-in aliases
await setTheme('dark');   // → resolves the 'mapstedDark' theme
await setTheme('light');  // → resolves the 'mapstedLight' theme

// A property's own theme id (from getThemes())
const theme = await setTheme('winterCampaign2026');
console.log('applied:', theme.name);

If the requested theme is not available for the property, setTheme() rejects with MAPSTED-1085 (ERR_THEME_UNAVAILABLE).

List available themes

getThemes() returns every theme available for the current property. The list always includes the two built-in themes (mapstedLight, mapstedDark) plus any CMS-owned property themes.

import { getThemes } from '@mapsted/maps-js-api';

const themes = await getThemes();
for (const t of themes) {
  console.log(t._id, t.name);
}

React to theme changes

The themeChange event fires whenever the active theme changes (including changes triggered by the map's own UI, if enabled).

import { on } from '@mapsted/maps-js-api';

on('themeChange', ({ themeId, theme }) => {
  console.log('theme is now', themeId, theme);
});

Both setTheme() and getThemes() are async — always await them (or handle the returned Promise). See the Theme type for the full shape.