TomTom Maps for JavaScript
    Preparing search index...

    Class StylingFoundationsModule

    The foundations of the whole map's look, with sizes across every part of the style, the ten map colours and the accent, the projection, the sky and the light on the 3D buildings.

    It is the tier between showing or hiding a part of the map 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. The ids form the StylingFoundationsKnobId union, and stylingFoundationsKnobCatalogue lists each one's kind, range and description as data, with no map needed to read it. Each id is its path into StylingFoundationsModuleConfig. setKnob, setKnobs, getKnob and resetKnob set, read and unset knobs by id, as on every module.

    The catalogue's appliesTo says which styles a knob works on. any-style knobs (sizes, widths) scale whatever the style already does, so they survive style-version bumps. A zoom ramp has each stop's output scaled, and any other expression E becomes ["*", 1.3, E]. tomtom-styles knobs (the map colours) reach their layers through the TomTom styles this SDK version is verified against. On a style layer they do not recognise, setting one warns once and does nothing.

    After every setStyle that carries state over, the settings are re-applied on top of whatever the other modules restored. A clean switch (resetState: true) drops them.

    Each part of the map's look belongs to its own module. POIsModule sizes and colours the POIs, TrafficFlowModule and TrafficIncidentsModule the traffic lines, TerrainModule the hillshade, and BaseMapModule shows and hides the layer groups and the road markings within them. The sizes here compose with theirs, so labels.sizeFactor and the POIs' sizeFactor multiply on the POI labels.

    import { getKnob, setKnobs, StylingFoundationsModule, stylingFoundationsKnobCatalogue } from '@tomtom-org/maps-sdk/map';

    const styling = await StylingFoundationsModule.get(map);
    setKnobs(styling, stylingFoundationsKnobCatalogue, { 'labels.sizeFactor': 1.2, 'colors.water': '#7cc4e8' });

    // The catalogue as data, and each knob's value in force:
    for (const knob of stylingFoundationsKnobCatalogue) {
      console.log(knob.id, knob.kind, knob.range, getKnob(styling, stylingFoundationsKnobCatalogue, knob.id));
    }

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

    Map Styling Guide

    Hierarchy (View Summary)

    Index
    events layers sourceAndLayerIDs
    applyConfig exportStyle getConfig resetConfig setMapColors updateConfig get

    • The lifecycle events of this module. The module owns no map features, so it has no user interaction events. config-change fires with the full settings after every knob change.

      Returns StylingFoundationsEvents

      styling.events.on('config-change', (settings) => localStorage.setItem('styling', JSON.stringify(settings)));
    • get layers(): { query: (query: LayerQuery) => LayerSelection }

      The advanced tier, with raw MapLibre paint, layout and filter edits over a query of the style's own layers, re-applied across style switches. These edits are coupled to the style version, as LayerSelection explains, so prefer a knob or setMapColors wherever one covers the intent.

      Returns { query: (query: LayerQuery) => LayerSelection }

      styling.layers.query({ group: 'roadLabels' }).setPaint({ 'text-color': '#93c5fd' });
    • get sourceAndLayerIDs(): Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      The MapLibre source and layer IDs of all sources this module creates and manages.

      Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

      A record mapping each source name to its MapLibre source ID and an array of the IDs of that source's layers.

      Use these IDs 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
      ids.mySource.layerIDs.forEach(layerId => {
        map.mapLibreMap.setLayoutProperty(layerId, 'visibility', 'visible');
      });

    • Applies a configuration to this module.

      The module updates its behaviour and appearance to match. It stores the configuration and reapplies it automatically when the map style changes.

      Parameters

      Returns void

      The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.

      Use it for settings your code writes. It takes every setting, typed, including the ones no knob covers (layer specs, callbacks, MapLibre expressions), and checks no value at run time. For settings held as data, from a control, storage or a language model, use setKnobs.

      // Apply a new configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

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

    • Exports the style as currently rendered, with every knob applied, as a MapLibre style specification to save, diff or serve yourself.

      Returns StyleSpecification

      It includes whatever the SDK's data modules (places, routes) have on the map. Its tile URLs carry the API key the map was created with, so strip or rotate the key before publishing. Labels set in a customTypeface come out in the style's own Noto faces, since only the SDK can draw font files beside the glyph service.

    • Returns a shallow copy of the current module configuration, or undefined if none is applied.

      Returns NonNullable<StylingFoundationsModuleConfig> | undefined

      A shallow copy of the current configuration, or undefined. It is a copy so that you can't modify the internal state by accident.

      Only the top-level properties are copied. Nested objects and arrays still reference the original configuration. This is enough for most use cases, but keep it in mind with complex configurations.

      // Apply a configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

      // Later, retrieve the current configuration
      const currentConfig = myModule.getConfig();
      console.log(currentConfig); // { visible: true, color: '#E63312' }

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

    • Resets this module's configuration to its default values.

      It clears any applied configuration and restores the module to its initial state, the same as calling applyConfig(undefined).

      Returns void

      The module then behaves as if no configuration was ever applied. Any custom settings, styling or behaviour changes are replaced with default values.

      // Apply some configuration
      myModule.applyConfig({ visible: true, color: '#E63312' });

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

    • Recolours the whole base map with up to ten semantic colours in one call, and sets accent, the default colour of routes, geometries and places (TomTomMap.mapColors).

      The ten are the style themes' Foundations palette, each listed with what it reaches under MapColorName. Partial objects are fine. The colours you leave out stay as they are, except on the mono styles, which derive the other nine from land as their theme does. There, the theme's own formulas re-derive them from the given land.

      Parameters

      • colors: MapColors

        The colours to set, as CSS colour strings.

      Returns void

      Each colour re-derives every shade the style built from it, such as a trunk variant, an outline or a tunnel, at the style's own HSL offset, so those relationships survive the recolour. The colours are also the colors.* knobs, so getKnob, resetKnob and settings persistence apply.

      The offsets come from the loaded style, which makes a palette a recolour and not an inversion. Dark land over streetLight pushes the derived shades to the ends of their range, so switch to streetDark 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' });
      resetKnob(styling, stylingFoundationsKnobCatalogue, 'colors.roadMajor'); // one colour back to the style
      styling.setMapColors(deriveMapColors(['#0b2a3a', '#0fa8c8', '#f6efe3'])); // map-theme plugin assigns the roles

    • Changes part of the configuration and keeps the rest.

      The given properties are laid over the current configuration one level deep, so a nested object you pass replaces the one that was there. The result is applied with applyConfig. This works the same on every module, whatever its applyConfig does with a whole configuration.

      Parameters

      • partial: Partial<NonNullable<CFG>>

        The properties to change.

      Returns void

      Use it for settings your code writes, as applyConfig: typed, and not checked at run time. To change nested values and keep the ones beside them, or to set values held as data, use setKnobs, which reaches each by its path and checks it.

      routing.applyConfig({ displayUnits: { distance: { type: 'imperial_us' } }, color: '#0a3653' });
      routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial

      applyConfig to apply a whole configuration

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

      Parameters

      Returns Promise<StylingFoundationsModule>

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

      The module styles the sources and layers the map style already provides, so every map has exactly one instance. A second get() returns the same instance and merges the given settings into what it already holds, as updateConfig does.

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

    Settings
    Member Visibility

    On This Page
    Accessors
    Methods