Map styling

The Styling Module restyles the base map, its POIs and the traffic overlays through semantic knobs: bigger labels, thicker roads, no exit numbers, orange for slow traffic. It sits between hiding whole layer groups with the Base Map Module and editing individual MapLibre layers by hand — and unlike either, it is designed to be read by machines: the whole catalogue of knobs is available as data.

Initialization

import { TomTomMap, StylingModule } from '@tomtom-org/maps-sdk/map';

const map = new TomTomMap({ mapLibre: { container: 'map' } });
const styling = await StylingModule.get(map);

The module is shared per map: a second get() returns the same instance. Pass settings to apply them right away, for instance restored from storage:

const styling = await StylingModule.get(map, { 'labels.sizeFactor': 1.2, 'buildings.3d': true });

Knobs

Every adjustable thing is a knob with a stable id. Set one with set, read it with get, restore the style's own value with reset:

styling.set('labels.sizeFactor', 1.3);        // every base-map label 30% bigger
styling.set('roads.widthFactor', 0.8);        // thinner roads, hierarchy kept
styling.set('roads.exitNumbers', false);      // no exit number badges
styling.set('buildings.3d', true);            // extruded buildings
styling.set('pois.minZoom', 10);              // POIs appear from zoom 10
styling.set('traffic.flow.slowColor', '#f59e0b');

styling.get('roads.widthFactor');             // 0.8
styling.reset('roads.widthFactor');           // back to the style's width
styling.reset();                              // everything back to the style as shipped

Values are validated before anything is touched: a factor outside its range or a string that is not a colour throws a RangeError that names the knob and its range.

Colour knobs re-derive the shades the style built from that colour: recolouring slow traffic recolours its darker outline by the same offset, so the tube keeps reading as designed. Ranges follow TomTom Map Maker's validated grammar, so a value that looks right in the designer's tool looks right here.

The catalogue: describe()

describe() returns the same knobs as data — kind, range, default, current value, whether it is overridden and how many layers of the loaded style it reaches. Build a control panel from it, hand it to an AI agent, or diff two calls:

const { knobs } = styling.describe();

for (const knob of knobs) {
    // knob.id, knob.kind ('factor' | 'number' | 'toggle' | 'color'), knob.description,
    // knob.range?, knob.default, knob.current, knob.overridden, knob.available, knob.appliesTo
}

The playground above is exactly that: its panel is generated from the catalogue, so it shows whatever the loaded style can do.

Two things are worth copying from it when you wire controls up. A slider or a colour picker fires input far faster than a restyle runs, so coalesce the calls into one set per animation frame (last value wins) and apply the final value on change; the readout can follow every event, since updating a label costs nothing. And if you rebuild the panel from the config-change event, skip the rebuild for changes your own controls made — set emits the event, so rebuilding mid-drag replaces the input under the pointer. Rebuild on external changes only: a reset, a setStyle, or an agent.

Settings: persist, share, re-apply

getConfig() returns the overridden knobs as a plain object; applyConfig() takes one back. It serializes cleanly, so styling can live in local storage, a URL or a pull request, and re-applying it on a later SDK version keeps working for as long as the knob ids do:

localStorage.setItem('map-styling', JSON.stringify(styling.getConfig()));
// …later
styling.applyConfig(JSON.parse(localStorage.getItem('map-styling')));

styling.events.on('config-change', (settings) => save(settings));

Style changes

Settings survive map.setStyle(...): the module re-applies them once the new style has loaded, after the other modules have restored themselves, so knobs always land on top. A clean switch (resetState: true) drops them along with the rest of the SDK state. See Map styles.

How durable is this?

Two kinds of knobs, told apart by appliesTo in the catalogue:

• any-style knobs (sizes, widths) wrap whatever the style already does — text-size: E becomes ["*", 1.3, E] — so they need no knowledge of the style. They work on a custom style of your own too.
• tomtom-styles knobs (toggles, colours, POI zoom) reach their layers through a taxonomy the TomTom styles declare, and the SDK re-verifies them against the styles it ships with. On a style that does not declare it, the knob reports available: false, warns once in the console and does nothing, so you can branch on it before offering the knob at all.

That is the contract: one call the SDK re-verifies on every style release, instead of a setPaintProperty block against layer ids that nobody tests again. Which style version the SDK verified against is our business, not yours — available is the answer you need, and it is true of the style actually loaded.

Interplay with other modules

The map modules split along one line: what is shown versus how the style draws it.

• BaseMapModule, TrafficFlowModule, TrafficIncidentsModule, POIsModule and HillshadeModule decide what is shown from one style part each: layer groups on or off, incident and POI categories, hillshade on or off.
• StylingModule decides how the style draws all of it: sizes, widths, colours and zoom thresholds across the base map, the traffic tiles, the POI layers and hillshade, plus the map-level view state. It is not a base-map-only module.
• Data modules (RoutingModule, PlacesModule, geometries, BYOD) draw their own layers and style them through their own configuration. Knobs never touch those layers.

The knobs live in one module rather than on each style-part module because many of them are cross-cutting (labels.sizeFactor, roads.widthFactor, a brand colour that reaches land, water, roads and labels at once), because knobs that reach the same paint property compose from one shared record of the style's original values, because they must re-apply in a single pass after every module has restored itself on a style change, and because an agent or a control panel wants one describe() and one settings object for the whole look. The per-part modules keep their small contracts and stay free of style-version coupling.

Where the two sides meet: toggles set layer visibility, as BaseMapModule.setVisible and POIsModule.setVisible do for whole groups, and the later call wins. pois.zoomShift rewrites the POI layer filters, which POIsModule.filterCategories also narrows: the two compose, so either can be set at any time and neither drops the other.

Anything else

For what the knobs do not cover, map.mapLibreMap remains the escape hatch — powerful, and coupled to the layer ids of the style version you tested against. Prefer a knob where one exists.

API reference

For complete documentation see the StylingModule API Reference.

Related guides and examples

• Map styles — switching styles, resetState, custom styles
• Base map — layer group visibility
• Traffic flow and Traffic incidents — the overlays the traffic knobs colour
• AI coding with the SDK — the agent-toolkit exposes the catalogue as describeMapStyling / setMapStyling