TomTom Maps SDK for JavaScript
This is the documentation of version 0.56.0. Go to the latest version, 1.0.0-rc.5.
TomTom Maps for JavaScript
    Preparing search index...

    Class StylingModule

    Semantic styling of the base map, traffic and POIs — the tier between hiding a layer group and hand-editing MapLibre layers.

    Every adjustable thing is a knob with a stable id, a kind, a range and a default read from the loaded style. describe returns that catalogue as data, so a UI or an AI agent can build controls, validate values and diff state without knowing anything about the style's layers.

    Which styles a knob works on is appliesTo in the catalogue. any-style knobs (sizes, widths) wrap whatever the style already does — text-size: E becomes ["*", 1.3, E] — so they work on a custom style too. tomtom-styles knobs (toggles, colours) reach their layers through the TomTom styles this SDK version is verified against; on any other style they report available: false, warn once and do nothing rather than failing silently.

    Style changes. Settings are re-applied after every setStyle that carries state over, on top of whatever the other modules restored, and dropped on a clean switch (resetState: true).

    Interplay with other modules. Toggles set layer visibility, as BaseMapModule and POIsModule do for whole groups; 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.

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

    const styling = await StylingModule.get(map);
    styling.set('labels.sizeFactor', 1.2);
    styling.set('roads.exitNumbers', false);
    styling.set('traffic.flow.slowColor', '#f59e0b');

    // Everything a control panel or an agent needs, as data:
    for (const knob of styling.describe().knobs) {
      console.log(knob.id, knob.kind, knob.range, knob.current);
    }

    // Serializable, diffable, re-applicable:
    const saved = styling.getConfig();
    styling.resetConfig();
    styling.applyConfig(saved);

    Map Styling Guide

    Hierarchy (View Summary)

    Index
    events sourceAndLayerIDs
    applyConfig applyPreset describe exportStyle get getConfig reset resetConfig set setMapColors waitUntilModuleReady get
    • get events(): StylingEvents

      Lifecycle events of this module. The module owns no map features, so there are no user interaction events; config-change fires with the full settings after every knob change.

      Returns StylingEvents

      styling.events.on('config-change', (settings) => localStorage.setItem('styling', JSON.stringify(settings)));
    • get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      Gets the source and layer identifiers for all sources managed by this module.

      This property provides access to the MapLibre source and layer IDs that were created and are managed by this module. These IDs can be used to interact directly with MapLibre's API or to identify which layers belong to this module.

      Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      A record mapping each source name to its corresponding source ID and layer IDs. Each entry contains the MapLibre source identifier and an array of layer identifiers associated with that source.

      The returned IDs are useful when you need to:

      • Directly manipulate layers using MapLibre's native API
      • Identify which layers on the map belong to this module
      • Set layer ordering or positioning relative to other layers
      • Access source or layer properties through MapLibre methods
      const ids = myModule.sourceAndLayerIDs;
      console.log(ids);
      // {
      //   mySource: {
      //     sourceID: 'my-source-id',
      //     layerIDs: ['layer-1', 'layer-2']
      //   }
      // }

      // Use with MapLibre API
      const map = myModule.mapLibreMap;
      ids.mySource.layerIDs.forEach(layerId => {
        map.setLayoutProperty(layerId, 'visibility', 'visible');
      });

    • Applies a configuration to this module.

      This method updates the module's behavior and appearance based on the provided configuration. The configuration is stored internally and will be automatically reapplied if the map style changes.

      Parameters

      • config: StylingSettings | undefined

        The configuration object to apply to the module. Pass undefined to reset the configuration to default values.

      Returns void

      When a configuration is applied, the module updates its visual representation and behavior accordingly. The configuration persists across map style changes, ensuring consistent module behavior even when the map's base style is modified.

      Unless a module documents otherwise, the given configuration replaces the current one rather than being merged into it. To change one part of it, spread the current configuration into the new one: myModule.applyConfig({ ...myModule.getConfig(), theme }).

      // Apply a new configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Reset to default configuration
      myModule.applyConfig(undefined);
      • resetConfig for a convenience method to reset configuration
      • getConfig to retrieve the current configuration

    • Applies a preset: a named bundle of knob settings the SDK ships for a common intent (data-viz, night-driving, minimal, globe, terrain). See describe().presets for what each one sets.

      Parameters

      • id: "terrain" | "globe" | "data-viz" | "night-driving" | "minimal"

        The preset to apply.

      • options: { merge?: boolean } = {}

        merge: true lays the preset over the current settings instead of replacing them (the default), so knobs the preset does not mention keep their values.

      Returns void

      Error for an unknown preset id.

      styling.applyPreset('data-viz');
      styling.set('labels.sizeFactor', 1.1); // then adjust

      styling.applyPreset('globe', { merge: true }); // keep the rest, switch to a globe with a sky

    • The styling catalogue for the loaded style: every knob with its kind, range, default, current value and how many layers it reaches.

      Returns StylingCatalogue

      Meant to be consumed as data — build a control panel from it, hand it to an agent, or diff two calls. Knob ids and the shape of the entries are public API and change additively only.

      const { knobs } = styling.describe();
      const sliders = knobs.filter((knob) => knob.kind === 'factor' && knob.available);

    • The style as currently rendered — the loaded style with every knob applied — as a MapLibre style specification, to save, diff, serve yourself, or load back as a custom style.

      Returns StyleSpecification

      It includes whatever the SDK's data modules (places, routes) have on the map, and its tile URLs carry the API key the map was created with: strip or rotate it before publishing.

    • The value a knob currently has: the override if one is set, otherwise the style's own default.

      Type Parameters

      • ID extends
            | "pois.minZoom"
            | "pois.zoomShift"
            | "view.projection"
            | "view.sky"
            | "view.skyColor"
            | "view.horizonColor"
            | "view.spaceColor"
            | "view.terrain"
            | "view.terrainExaggeration"
            | "labels.sizeFactor"
            | "symbols.sizeFactor"
            | "roads.widthFactor"
            | "pois.sizeFactor"
            | "pois.labelColor"
            | "pois.labelOutlineColor"
            | "pois.microMarkers"
            | "roads.exitNumbers"
            | "roads.shields"
            | "roads.arrows"
            | "roads.restricted"
            | "roads.underConstruction"
            | "buildings.footprints"
            | "buildings.3d"
            | "traffic.flow.freeColor"
            | "traffic.flow.slowColor"
            | "traffic.flow.queueingColor"
            | "traffic.flow.stationaryColor"
            | "traffic.flow.closedColor"
            | "traffic.flow.widthFactor"
            | "traffic.incidents.minorColor"
            | "traffic.incidents.moderateColor"
            | "traffic.incidents.majorColor"
            | "traffic.incidents.closedColor"
            | "traffic.incidents.widthFactor"
            | "colors.land"
            | "colors.water"
            | "colors.vegetation"
            | "colors.park"
            | "colors.artificial"
            | "colors.roadMajor"
            | "colors.road"
            | "colors.roadOutline"
            | "colors.label"
            | "colors.labelOutline"

      Parameters

      • id: ID

        The knob to read.

      Returns StylingKnobValueOf<ID> | undefined

      The current value, or undefined when the style defines it as a data-driven expression that no single value stands for.

      styling.get('labels.sizeFactor'); // 1 until set

    • Retrieves a copy of the current module configuration.

      This method returns a shallow copy of the configuration object that is currently applied to the module. If no configuration has been applied, it returns undefined.

      Returns NonNullable<StylingSettings> | undefined

      A shallow copy of the current configuration object, or undefined if no configuration is currently applied. The returned object is a copy to prevent unintended modifications to the internal state.

      The returned configuration object is a shallow copy, which means that while the top-level properties are copied, any nested objects or arrays are still referenced from the original configuration. This is sufficient for most use cases but should be kept in mind when dealing with complex configurations.

      // Apply a configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Later, retrieve the current configuration
      const currentConfig = myModule.getConfig();
      console.log(currentConfig); // { visible: true, opacity: 0.8 }

      // When no config is applied
      myModule.resetConfig();
      console.log(myModule.getConfig()); // undefined

    • Restores the style's own values for one knob, or for all of them.

      Parameters

      • Optionalid:
            | "pois.minZoom"
            | "pois.zoomShift"
            | "view.projection"
            | "view.sky"
            | "view.skyColor"
            | "view.horizonColor"
            | "view.spaceColor"
            | "view.terrain"
            | "view.terrainExaggeration"
            | "labels.sizeFactor"
            | "symbols.sizeFactor"
            | "roads.widthFactor"
            | "pois.sizeFactor"
            | "pois.labelColor"
            | "pois.labelOutlineColor"
            | "pois.microMarkers"
            | "roads.exitNumbers"
            | "roads.shields"
            | "roads.arrows"
            | "roads.restricted"
            | "roads.underConstruction"
            | "buildings.footprints"
            | "buildings.3d"
            | "traffic.flow.freeColor"
            | "traffic.flow.slowColor"
            | "traffic.flow.queueingColor"
            | "traffic.flow.stationaryColor"
            | "traffic.flow.closedColor"
            | "traffic.flow.widthFactor"
            | "traffic.incidents.minorColor"
            | "traffic.incidents.moderateColor"
            | "traffic.incidents.majorColor"
            | "traffic.incidents.closedColor"
            | "traffic.incidents.widthFactor"
            | "colors.land"
            | "colors.water"
            | "colors.vegetation"
            | "colors.park"
            | "colors.artificial"
            | "colors.roadMajor"
            | "colors.road"
            | "colors.roadOutline"
            | "colors.label"
            | "colors.labelOutline"

        The knob to reset; omit to reset every knob (same as resetConfig).

      Returns void

      styling.reset('labels.sizeFactor');
      styling.reset(); // back to the style as shipped

    • Resets the configuration of this module to its default values.

      This is a convenience method that clears any previously applied configuration and restores the module to its initial state. This is equivalent to calling applyConfig(undefined).

      Returns void

      After calling this method, the module will behave as if no configuration was ever applied. Any custom settings, styling, or behavior modifications will be removed and replaced with default values.

      // Apply some configuration
      myModule.applyConfig({ visible: true, opacity: 0.5 });

      // Later, reset to defaults
      myModule.resetConfig();
      • applyConfig to apply a new configuration
      • getConfig to retrieve the current configuration before resetting

    • Sets one knob. The value is validated against the knob's kind and range before anything is touched, and applied to every layer the knob reaches.

      Type Parameters

      • ID extends
            | "pois.minZoom"
            | "pois.zoomShift"
            | "view.projection"
            | "view.sky"
            | "view.skyColor"
            | "view.horizonColor"
            | "view.spaceColor"
            | "view.terrain"
            | "view.terrainExaggeration"
            | "labels.sizeFactor"
            | "symbols.sizeFactor"
            | "roads.widthFactor"
            | "pois.sizeFactor"
            | "pois.labelColor"
            | "pois.labelOutlineColor"
            | "pois.microMarkers"
            | "roads.exitNumbers"
            | "roads.shields"
            | "roads.arrows"
            | "roads.restricted"
            | "roads.underConstruction"
            | "buildings.footprints"
            | "buildings.3d"
            | "traffic.flow.freeColor"
            | "traffic.flow.slowColor"
            | "traffic.flow.queueingColor"
            | "traffic.flow.stationaryColor"
            | "traffic.flow.closedColor"
            | "traffic.flow.widthFactor"
            | "traffic.incidents.minorColor"
            | "traffic.incidents.moderateColor"
            | "traffic.incidents.majorColor"
            | "traffic.incidents.closedColor"
            | "traffic.incidents.widthFactor"
            | "colors.land"
            | "colors.water"
            | "colors.vegetation"
            | "colors.park"
            | "colors.artificial"
            | "colors.roadMajor"
            | "colors.road"
            | "colors.roadOutline"
            | "colors.label"
            | "colors.labelOutline"

      Parameters

      • id: ID

        The knob to set; see describe for the catalogue.

      • value: StylingKnobValueOf<ID>

        A number for factor/number knobs (within range), a boolean for toggle knobs, a CSS colour string for color knobs.

      Returns void

      RangeError when the value is not valid for the knob; Error for an unknown id.

      styling.set('roads.widthFactor', 1.3);
      styling.set('buildings.3d', true);
      styling.set('traffic.flow.stationaryColor', 'hsl(0, 100%, 40%)');

    • Recolours the whole base map with up to ten semantic colours in one call — Map Maker's Foundations palette, each listed with what it reaches under MapColorName. Partial objects are fine; colours not given stay as they are.

      Parameters

      • colors: MapColors

        The colours to set, as CSS colour strings.

      Returns void

      Each colour re-derives every shade the style built from it — a trunk variant, an outline, a tunnel — at the style's own HSL offset, so those relationships survive the recolour. The ten are also the colors.* knobs, so describe(), reset and settings persistence apply.

      Those offsets come off the loaded style, which makes a palette a recolour and not an inversion: dark land over standardLight pushes the derived shades to the ends of their range, so switch to standardDark first.

      RangeError for a value that is not a colour; Error for an unknown colour name.

      styling.setMapColors({ land: '#f3f5f7', water: '#accbe2', roadMajor: '#a1b8ce', label: '#364659' });
      styling.reset('colors.roadMajor'); // one colour back to the style

    • Retrieves the styling module of the given map, creating it on first use.

      Parameters

      • map: TomTomMap

        The TomTomMap instance to style.

      • Optionalsettings: StylingSettings

        Optional knob values to apply right away, e.g. restored from storage.

      Returns Promise<StylingModule>

      A promise that resolves once the map style is loaded and the settings are applied.

      Instances: the module styles the sources and layers the map style already provides, so every map has exactly one — a second get() returns the same instance, with the given settings applied on top of what it already holds.

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

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods