TomTom LogoDocs
Products
Resources
Pricing
Sign in
Maps SDK for JavaScript
Introduction
Guides
Examples
API Reference

Editing style layers

VERSION 1.0.0-rc.3PUBLIC PREVIEW

styling.layers edits the loaded style’s layers directly, for what the knobs of the Styling Foundations module don’t cover. This advanced tier depends on the style version, so prefer a knob or setMapColors wherever one covers your need.

The advanced tier: styling.layers

styling.layers.query(...) selects style layers and returns a LayerSelection to edit their paint, layout, filter or visibility:

styling.layers.query({ group: 'roadLabels' }).setPaint({ 'text-color': '#93c5fd' });
styling.layers.query({ metadataGroups: ['water'], layerTypes: ['fill'] }).setPaint({ 'fill-opacity': 0.6 });
styling.layers.query({ idIncludes: ['railway'] }).setVisible(false);
styling.layers.query({ group: 'trafficFlow', layerTypes: ['line'] }).setPaint({ 'line-blur': 2 });
styling.layers.query({ group: 'roadLabels' }).reset(); // undo the edits made on those layers
styling.layers.query({ group: 'railways' }).layerIds;  // what matched, in draw order
Query fieldSelects by
groupA base-map group, named as in BaseMapModule, or the layers of another style-owned module: pois, trafficFlow, trafficIncidents, hillshade (styleModuleLayerGroupNames)
metadataGroupsThe style’s own metadata.group values, for groups the SDK does not name
layerTypesMapLibre layer types: line, fill, symbol, …
sourceLayersVector-tile source layers: roads, places, poi, …
idIncludes, idExcludesFragments the layer id must, or must not, contain (case-insensitive)

A layer must match every field you give, so other fields narrow a group. A query covers every style layer, whichever module shows or hides it.

Only the style’s own layers

styling.layers and the knobs reach only the layers the loaded style declares. To override the layers a data-owned module adds, use its own layers configuration, which it merges over its defaults and keeps across style switches:

ModuleIts layers entries
Placesmain, micro, selected, the cluster layers, and those of its connections and entry points
Routingthe route lines, waypoints, sections and their labels, by group (mainLines, sections, …)
Geometries, Reachable rangesfill, line, label, lineLabel
Traffic incident detailsthe incident lines, from highlightHalo to innerPattern, and the three markers
Traffic area analyticsheatmap, each grid’s fill, outline, extrusion and highlight, and the region

The layers you add through map.mapLibreMap are yours to style.

In the demo below, one switch fades the traffic flow, POIs and road labels through styling.layers groups, and brings a city’s incidents and boundary forward through their modules’ layers configs.

What an edit keeps

  • After a style switch that carries state, the SDK re-applies your edits on top of the knobs, as long as the layers still exist. A clean switch (resetState: true) drops every edit.
  • setFilter replaces the filter the style gave a layer. The filters other modules add, such as POI categories, still narrow it.
  • setVisible(true) doesn’t show a layer that its module hides, such as the POIs after pois.setVisible(false).
  • Edits are not part of getConfig(), because they apply to this style only.

How durable is it?

Layer ids, property expressions and even which layers exist depend on the style version the map loads. An edit through a query that matches nothing warns once and does nothing. Reading its layerIds gives an empty list without a warning.

You can still use map.mapLibreMap underneath (which to use when). Note that a setPaintProperty on a style layer there is not re-applied after a style switch.

  • Map styling — the knobs, and which of them depend on the TomTom styles
  • About MapLibre — the raw MapLibre map underneath