Place styling

The Places module draws places in its own look, set by the marker type, colour, icon and label settings below. Each plain-valued setting is a knob in placesKnobCatalogue. Two outside settings reach these layers. The map’s accent colours markers you give no colour, and the knobs that restyle the style’s POIs restyle the marker types that borrow their look.

Marker type

markerType sets the marker every place is drawn with, at creation or at runtime:

• pin (default) - Teardrop pins.
• circle-icon - Circles with the category icon centred.
• base-map - The style’s own POI look, through main, selected and micro layers, so places blend in with the map’s POIs.
  • For dense results, hide main to draw only the small micro dots.
• pin-clustered - Pins that merge into a counted cluster when zoomed out (Clusters).

1
const placesModule = await PlacesModule.create(map, { markerType: 'base-map' });
2
placesModule.updateConfig({ markerType: 'circle-icon' });
3

4
// Micro dots only: `base-map` with a hidden `main` layer
5
const microPlaces = await PlacesModule.create(map, {
6
    markerType: 'base-map',
7
    layers: { main: { layout: { visibility: 'none' } } },
8
});

base-map, circle-icon and pin-clustered borrow the look of the style’s POIs. Borrowed looks lists which POI knobs restyle each marker type.

Clusters

With the pin-clustered marker type, cluster sets how places cluster and how the count badge looks. Other marker types ignore it. badge styles the badge of both single-category and mixed-category clusters, and source takes MapLibre’s cluster options:

1
const placesModule = await PlacesModule.create(map, {
2
    markerType: 'pin-clustered',
3
    // The per-place value the cluster aggregates
4
    extraFeatureProps: {
5
        connectorCount: (place) =>
6
            place.properties.chargingPark?.connectors.reduce((total, { count }) => total + count, 0) ?? 0,
7
    },
8
    cluster: {
9
        badge: { color: '#3f9cd9', radius: { single: 13, mixed: 18 } },
10
        source: {
11
            radius: 100, // default 60
12
            maxZoom: 14, // default 17
13
            // Total charging points across each cluster
14
            properties: { connectors: ['+', ['get', 'connectorCount']] },
15
        },
16
    },
17
    // An aggregated value lands on the cluster feature's properties
18
    layers: { clusterCount: { layout: { 'text-field': ['get', 'connectors'] } } },
19
});

• A layers override of clusterBadge, clusterCount, clusterMixedBadge or clusterMixedCount wins over badge for the paint and layout properties it names, and badge sets the rest.
• badge.label sets the count’s color and size.
• source takes MapLibre’s clusterRadius, clusterMaxZoom, clusterMinPoints and clusterProperties as radius, maxZoom, minPoints and properties.
• Changing source at runtime recreates the places source and shows its places again.
• You can’t switch clustering on in source, because the marker type does. The clusterBaseMapIconIDs key of properties is reserved for the module’s own aggregator.

Colour

color colours the module’s own drawing: the default pin fill, the label of a hovered or clicked place, connection lines and entry points. Connection labels take a darker shade of it on a light map and a lighter one on a dark map. Entry points take the darker one on a light map.

1
const placesModule = await PlacesModule.create(map, { color: '#2A9D8F' });

• A more specific setting wins for its element, such as icon.default.style.fillColor for the pin, and label.color or a layers.* paint override for a label or layer.
• If you don’t set it, it is the map’s accent, and the markers repaint when the accent changes. Once you set it, accent changes leave them as they are.
• Cluster badges don’t use it. cluster.badge.color sets them.

Label styling

label sets the content and look of the labels next to the markers:

1
import { PlacesModule, type PlaceLabelConfig } from '@tomtom-org/maps-sdk/map';
2

3
// POI names red, other places blue
4
const label: PlaceLabelConfig = {
5
    title: (place) => place.properties.poi?.name ?? place.properties.address.freeformAddress,
6
    color: ['match', ['get', 'type'], 'POI', '#D32F2F', '#1976D2'],
7
    haloWidth: 2,
8
};
9
const placesModule = await PlacesModule.create(map, { label });
10

11
// `label` replaces the whole label: spread the current one to change a single field
12
placesModule.updateConfig({ label: { ...placesModule.getConfig()?.label, opacity: 0.8 } });

• PlaceLabelConfig takes the label settings shared across modules (size, color, haloColor, haloWidth, opacity and font), plus the place’s own title and distance, how far the text sits from the icon, in ems.
• By default, labels follow the marker type. Under base-map they are the style’s POI labels, otherwise dark text on a light halo, reversed on a dark map. A hovered or clicked place’s label takes color.
• Set labels here, not with MapLibre’s setPaintProperty on the module’s layers. A style change or a marker type change rebuilds those layers from the configuration and drops what was written on them. A title computed from each place has no MapLibre equivalent.
• A layers.* override, such as layers.main.layout['text-size'], wins over label for the properties it names. Changing a setting covers how updateConfig merges.

Icon styling

icon.categoryIcons draws a category’s places with your own image, under every marker type. Places in other categories keep the marker type’s icon.

1
import { PlacesModule, type PlaceIconConfig } from '@tomtom-org/maps-sdk/map';
2

3
const icon: PlaceIconConfig = {
4
    categoryIcons: [
5
        { id: 'RESTAURANT', image: '/icons/food.png', pixelRatio: 2 },
6
        // A pin whose tip sits 10 pixels below its centre
7
        { id: 'HOTEL_OR_MOTEL', image: '/icons/hotel.png', pixelRatio: 2, offsetY: -10 },
8
    ],
9
};
10
const placesModule = await PlacesModule.create(map, { markerType: 'pin', icon });

• A place takes the entry for its own category, otherwise the first entry for the map category its own falls in. For example, RESTAURANT reaches an ITALIAN_RESTAURANT a search returns, and CAFE a CAFE_PUB.
  • That broader match takes only entries with an image, like the POIs module, so one list restyles these places and the map’s own POIs alike.
• offsetX and offsetY shift the image from its coordinate, in pixels. An entry that names a sprite icon by id alone ignores them.
• icon.default is the pin drawn for places without a matched category. style recolours it, and image replaces it. With an image, neither style nor the image’s offsets apply.
• icon.mapping picks the icon from your own data (Your own data).

Extra properties

extraFeatureProps adds properties to every place feature, for layers expressions to read with ['get', '<name>'] and for event handlers:

1
placesModule.updateConfig({
2
    extraFeatureProps: {
3
        firstCategory: (place) => place.properties.poi?.categories?.[0],
4
        brand: (place) => place.properties.poi?.brands?.[0] ?? '',
5
        source: 'search',
6
    },
7
});

An entry is a fixed JSON value or a callback that receives a Place and returns one. If the places you show have a narrower shape, such as search results with their relevance score, name it on the config, or as the type parameter of applyConfig / updateConfig. The callbacks, label.title and icon.mapping are then typed for it:

1
import type { SearchPlaceProps } from '@tomtom-org/maps-sdk/core';
2
import type { PlacesModuleConfig } from '@tomtom-org/maps-sdk/map';
3

4
const config: PlacesModuleConfig<SearchPlaceProps> = {
5
    extraFeatureProps: {
6
        relevance: (place) => place.properties.score,
7
    },
8
};

Layer positioning

By default, the markers sit above the map’s layers, and the connection lines below its labels. beforeLayerConfig (PlacesBeforeLayerConfig) moves them. It takes either one target for everything the module draws, 'top' or a key of mapStyleLayerIDs, or a record keyed by part, plus all for the parts it leaves out. The parts are named after the event scopes:

• places - The markers and their labels, selected places, clusters with their badges and counts, and entry points.
  • By default, the small POI dots of the base-map and pin-clustered marker types sit below the map’s place labels. A target puts them right under the markers.
• connections - The lines drawn by showConnections and their labels.

1
// The markers under the map's labels; the connections stay where they are
2
placesModule.updateConfig({ beforeLayerConfig: { places: 'lowestLabel' } });

• Each part keeps its own layers in order wherever it goes. With the same target, the connections stay under the markers.
• applyConfig or updateConfig restacks them at runtime, and resetConfig() puts them back.
• A target the style lacks, such as lowestRoadLine on the satellite style, puts the part on top.

Every setting as data

placesKnobCatalogue lists every plain-valued display setting of the module with its kind, its range or options and, if one value holds everywhere, its default. Each id is the setting’s path in the config. The catalogue reads with no map loaded, so a UI can build its controls from it:

1
import { placesKnobCatalogue } from '@tomtom-org/maps-sdk/map';
2

3
const badgeKnobs = placesKnobCatalogue.filter(({ id }) => id.startsWith('cluster.badge.'));
4
// [{ id: 'cluster.badge.color', kind: 'color', description: '…', default: '#000000' }, …,
5
//  { id: 'cluster.badge.radius.single', kind: 'number', description: '…', range: { min: 4, max: 32, step: 1, bounds: 'hard-min' }, default: 11 }, …]

• A default in words is not in the entry, because the accent, the theme, the zoom or the marker type decides it.
• setKnob, getKnob and resetKnob set, read and reset one by its id (Setting a knob by its id).
• label.font offers mapFonts. Order matters, because the first font the map has wins.
• cluster.badge.offset shifts a single-category cluster’s badge, in pixels. Mixed-category badges stay centred.
• placesKnobIds lists the ids in catalogue order, PlacesKnobId is their union, and PlacesKnobValueOf<ID> is the plain value one takes. The MapLibre expression a label or badge setting also accepts is not a knob value.
• The catalogue leaves out the label’s title, the cluster source’s properties, the icon images and mapping, the connections’ label, layers, beforeLayerConfig, extraFeatureProps and events, because they take callbacks, images, structured or MapLibre values.
• Entry points draw nothing until you set entryPoints, and cluster applies only under pin-clustered.
• Its entries share their shape, KnobEntry, with every module’s catalogue.

Related guides and examples

Related guides

• Places module - Showing places, events and the data shown
• Connections and entry points - The lines and entrances drawn around places
• Map modules - The knob kinds every catalogue shares
• POIs - The same categoryIcons list on the map’s own POIs

Related examples

• Places customization playground - Advanced place styling and customization techniques, with the pins drawn over or under the map’s labels
• Places default icon styling - One color per module instance, with the default pin’s outline set alongside
• POI category icons playground - One categoryIcons list restyling searched places and the map’s own POIs together
• Places clustering playground - How places cluster, how the count badge looks and what it counts
• Borrowed looks - base-map places restyled live by the knobs that restyle the style’s POIs