Map theme plugin

The Map Theme plugin themes a TomTomMap from wherever a look comes from: a brand's swatches, your page's CSS, a logo or a photo, a mood, an artist. It turns any of them into the ten map colours — land, water, roads, labels — which setMapColors applies to the whole base map.

What it is for

Every source comes down to a handful of colours, and one call assigns them their roles:

Installation

npm install @tomtom-org/maps-sdk maplibre-gl @tomtom-org/maps-sdk-plugin-map-theme

@tomtom-org/maps-sdk and culori are peer dependencies.

From colours

import { StylingModule } from '@tomtom-org/maps-sdk/map';
import { deriveMapColors } from '@tomtom-org/maps-sdk-plugin-map-theme';

const styling = await StylingModule.get(map);
const colors = deriveMapColors(['#1d3f8a', '#e63312', '#f5d000', '#111111', '#f4f1ea']);
styling.setMapColors(colors);

deriveMapColors returns all ten colours, so a UI can show what became what, and styling.set('colors.water', …) corrects one role. Applied through setMapColors, a theme is colors.* knobs: it survives setStyle and serialises with getConfig().

How colours get their roles

The assignment is deterministic; order does not matter and near-duplicates count once.

Roles no colour fits are derived from land — roads and outlines as shades of it, water and vegetation as muted hues — so one to eight colours always give a complete palette. mode: 'auto', the default, reads light or dark off the colours; pass { mode: 'light' } or { mode: 'dark' } to force it.

Light and dark styles

setMapColors re-derives each style's own shades at that style's offsets, so a dark theme over standardLight pushes them to black. mapColorsLightDark(colors) tells a dark theme from a light one — whether auto or the source decided it — so the map can switch first:

import { mapColorsLightDark } from '@tomtom-org/maps-sdk-plugin-map-theme';

const lightDark = mapColorsLightDark(colors);
if (lightDark !== map.styleLightDarkTheme) {
    await map.setStyle(lightDark === 'dark' ? 'standardDark' : 'standardLight');
}
styling.setMapColors(colors);

From your page's CSS

A map embedded in your own app can wear the app's brand: read the page's custom properties and its theme-color, and theme from those.

const css = getComputedStyle(document.documentElement);
const brand = ['--color-primary', '--color-accent', '--color-surface', '--color-text']
    .map((name) => css.getPropertyValue(name).trim())
    .concat(document.querySelector('meta[name="theme-color"]')?.content ?? [])
    .filter(Boolean);

styling.setMapColors(deriveMapColors(brand));

Use your design system's own property names. Colours in hex, rgb(), hsl() or a CSS name are read; anything else is skipped.

From a stylesheet

A whole stylesheet works too: a website's CSS, a design system's tokens, a file a user uploads. deriveMapColorsFromCss reads the colours it paints with and assigns them roles; it takes the CSS as text, so it needs no DOM.

import { deriveMapColorsFromCss } from '@tomtom-org/maps-sdk-plugin-map-theme';

// A File from an <input type="file" accept=".css">, or CSS a server fetched
styling.setMapColors(deriveMapColorsFromCss(await fileInput.files[0].text()));

• Most used wins: a colour counts every time a rule fills with it; borders and shadows count for less, translucent colours, a colour's own shades (a button's hover) and words in url() paths not at all.
• var() resolves as the page does: against the rule's own custom properties or the page root's, not one set on another selector (.inverse { --bg: … }).
• Greys don't crowd out the brand: the six colours (colorCount changes that) hold at most two greys, a background and a text colour, while colourful ones remain.
• Light or dark as the page is: the background on :root, html or body, or else the grey most rules fill with. Rules for one colour scheme (prefers-color-scheme, a .dark or .light class, data-theme="dark") are read only with that mode, and then override the defaults; auto reads the page as it is without them.

cssColors(cssText) returns the colours without assigning roles, for a UI that lets the user edit them first.

From an image

import { deriveMapColorsFromImage } from '@tomtom-org/maps-sdk-plugin-map-theme';

// A File from an <input type="file">, a Blob, an <img>, an ImageBitmap or a CORS-readable URL
styling.setMapColors(await deriveMapColorsFromImage(fileInput.files[0], { mode: 'dark' }));

The image is drawn into a 64×64 canvas; its six dominant colours (colorCount changes that) are assigned roles. A URL must be served with Access-Control-Allow-Origin; otherwise pass the File or Blob.

Without a DOM — a worker, a test, a server — decode the image yourself and pass { data, width, height } (ImagePixels, shaped like ImageData), or call dominantColors(pixels) and hand the result to deriveMapColors. Busy photos average into muted colours; pick from dominantColors by hand when that happens.

From a mood, an artist or a website you cannot read

A mood has no colours to read, and a page cannot fetch another origin's CSS (a server can, then hand it to deriveMapColorsFromCss), so these start with a model rather than a function:

• A coding agent reads the site's theme-color, :root custom properties and logo, or turns "warm earthy tones" or "like a Miró" into three to six hex colours, then writes the deriveMapColors call. The /tomtom-maps-sdk-js skill carries the recipes.
• In a conversation, the Agent Toolkit's setMapStyling({ theme: { colors } }) does the same at run time, and theme: { imageUrl } themes from an image. It switches to the light or dark variant of the standard style the theme needs.

Limits

• The assignment is a heuristic: it makes calls a designer wouldn't, which is why every role comes back for correction.
• Only the label contrast is guaranteed: a palette of near-equal lightness gives roads barely separable from land, and a label derived for a mid-lightness land takes whichever side reads, even against the mode.
• The image is sampled at 64×64: cheap and in-browser, and a small but striking colour can go missing.

API reference

deriveMapColors · mapColorsLightDark · deriveMapColorsFromCss · cssColors · deriveMapColorsFromImage · dominantColors

Related guides and examples

• Map styling — setMapColors and the ten colours
• Map theme from colours, an image or CSS