Class PlacesModule

Map module for displaying and managing place markers.

The PlacesModule provides functionality to display location markers (pins) on the map for points of interest, search results, or custom locations. It supports various marker styles, custom icons, text labels, and interactive events.

Remarks

Features:

Marker types (PlacesMarkerType): pins, circles, base-map POI look-alikes and clustered pins
One colour for the module's own drawing (PlacesModuleConfig.color)
Custom icons per POI category
Text labels with styling options
Data-driven styling via MapLibre expressions
Interactive events (click, hover, etc.)
Support for custom feature properties
EV charging station availability display (opt-in)
Entry points of places, for all of them or only hovered or clicked ones (opt-in)

EV Charging Station Availability: When displaying EV charging stations with availability data from getPlacesWithEVAvailability, the module can:

Show available/total charging points (e.g., "3/10")
Color-code availability (green = good, orange = limited, red = none/low)
Display as formatted text within the station's label

This feature is disabled by default. To enable it, set evAvailability.visible to true in the configuration.

Common Use Cases:

Search result visualization
Custom location markers
Store locators
EV charging station maps with real-time availability
Delivery/pickup points
Saved locations display

Example

// Create places module with pin markers
const placesModule = await PlacesModule.create(map, {
  icon: {
    categoryIcons: []
  },
  label: {
    title: (place) => place.properties.poi?.name || 'Unknown'
  },
  markerType: 'pin'
});

// Display places from search
await placesModule.show(searchResults);

// EV Charging Stations - Opt-in to availability display
const evStations = await PlacesModule.create(map, {
  evAvailability: { visible: true }
});
const results = await discoverPlaces({ filters: { poiCategories: ['CHARGING_LOCATION'] } });
evStations.show(await getPlacesWithEVAvailability(results)); // Shows availability

// Granular control: Enable for searched stations only, background stations without
const bgStations = await PlacesModule.create(map); // EV availability disabled
const searched = await PlacesModule.create(map, {
  evAvailability: { visible: true }
});

// Handle clicks
placesModule.events.on('click', (feature) => {
  console.log('Clicked:', feature.properties);
});

placesModule.events.on('hover', (feature) => {
  showTooltip(feature.properties.poi?.name);
});

See

Places Guide

Hierarchy (View Summary)

AbstractDataOwnedMapModule<PlacesSourcesAndLayers, PlacesModuleConfig>
- PlacesModule

Accessors

events

get events(): PlacesEvents

Returns PlacesEvents

sourceAndLayerIDs

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.
Remarks
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
Example
```
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');
});
```
Inherited from AbstractDataOwnedMapModule.sourceAndLayerIDs

Methods

applyConfig

applyConfig(
config: PlacesModuleConfig | undefined,
): void
Applies a configuration to this module, replacing the current one.
Type Parameters
- P extends CommonPlaceProps = CommonPlaceProps
 The place shape the label.title, icon.mapping and extraFeatureProps callbacks expect, as with PlacesModule.create.
Parameters
- config: PlacesModuleConfig | undefined
Returns void
Example
```
places.applyConfig<MyPlaceProps>({ label: { title: (place) => place.properties.storeName } });
```
Overrides AbstractDataOwnedMapModule.applyConfig

cleanEventState

cleanEventState(options: CleanEventStateOptions): void
Takes the event state off one of the shown features.
Parameters
- options: CleanEventStateOptions
Returns void
Example
```
module.cleanEventState({ id: feature.id });
```
Inherited from AbstractDataOwnedMapModule.cleanEventState

cleanEventStates

cleanEventStates(options?: CleanEventStatesOptions): void
Takes the given event states, or all of them, off the shown features.
Parameters
- Optionaloptions: CleanEventStatesOptions
Returns void
Example
```
module.cleanEventStates(); // every state
module.cleanEventStates({ states: ['hover'] }); // hovers only, selections stay
```
Inherited from AbstractDataOwnedMapModule.cleanEventStates

clear

clear(): Promise<void>
Removes all places from the map.

Returns Promise<void>
Remarks
- Clears all displayed places, their event states and the shown connections
- Does not reset styling configuration
- Module remains initialized and ready for new data
Example
```
await placesModule.clear();
```

clearConnections

clearConnections(): Promise<void>
Removes all connection lines from the map, leaving displayed places intact.

Returns Promise<void>
Example
```
await placesModule.clearConnections();
```

getConfig

getConfig(): NonNullable<PlacesModuleConfig> | undefined
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<PlacesModuleConfig> | 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.
Remarks
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.
Example
```
// 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
```
See
- applyConfig to modify the configuration
- resetConfig to clear the configuration
Inherited from AbstractDataOwnedMapModule.getConfig

getEventStates

getEventStates(): EventStateIds
Returns the ids of the shown features that have an event state, by state.

Returns EventStateIds
Remarks
The read side of putEventState and cleanEventStates: it reflects those and the states user interactions put. The ids are those getShown() and the event handlers hand back, so each can go straight back into putEventState.
Example
```
// Keep a list in sync with the selected feature
const { click: [selectedID] = [] } = module.getEventStates();

// Is this feature hovered?
const hovered = module.getEventStates().hover?.includes(feature.id) ?? false;
```
Inherited from AbstractDataOwnedMapModule.getEventStates

getShown

getShown(): {
connections: PlaceConnectionDisplay[];
places: Places<DisplayPlaceProps>;
}
Returns the currently shown places.

Returns { connections: PlaceConnectionDisplay[]; places: Places<DisplayPlaceProps> }
The places currently displayed on the map.
Remarks
places are the places given to show() as drawn: each carries the PlaceDisplayProps and its current eventState. connections are the ones given to showConnections(), including any skipped for an id no shown place has.
Example
```
const shown = placesModule.getShown();
console.log(`Showing ${shown.places.features.length} places`);
```

isVisible

isVisible(): boolean

Whether the module is set to be shown: its visible setting, true unless set. A shown module with nothing shown draws nothing; getShown() returns what is shown.

Returns boolean

Inherited from AbstractDataOwnedMapModule.isVisible

putEventState

putEventState(options: PutEventStateOptions): void
Puts an event state on one of the shown features, as a user interaction would.
Parameters
- options: PutEventStateOptions
Returns void
Remarks
The state is what the module's own layers draw (place pins and entry points, route outlines, geometries, details-module incidents, area-analytics cells), what layers of yours read with ['get', 'eventState'], and what getEventStates returns. It lasts as long as the shown feature does: through setVisible, style and configuration changes, not through a new show, a clear or a setStyle with resetState.
Example
```
// Select a feature from a list, as a click would
module.putEventState({ id: feature.id, state: 'click' });

// Hover a second one without taking the hover off the first
module.putEventState({ index: 2, state: 'hover', mode: 'add' });
```
Inherited from AbstractDataOwnedMapModule.putEventState

resetConfig

resetConfig(): void
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
Remarks
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.
Example
```
// Apply some configuration
myModule.applyConfig({ visible: true, color: '#E63312' });

// Later, reset to defaults
myModule.resetConfig();
```
See
- applyConfig to apply a new configuration
- getConfig to retrieve the current configuration before resetting
Inherited from AbstractDataOwnedMapModule.resetConfig

setVisible

setVisible(visible: boolean): void
Shows or hides everything the module draws.
Parameters
- visible: boolean
Returns void
Remarks
Stored as visible in the configuration. Showing and clearing data never change it: a hidden module keeps its data, through style changes too, and draws it again on setVisible(true).

Showing leaves hidden what the configuration turns off: a route section type that is off, the layers a place marker type does not use.
Example
```
module.setVisible(false);
await module.show(data); // stays hidden
module.setVisible(true);
```
Inherited from AbstractDataOwnedMapModule.setVisible

show

show(places: ShownPlaces): Promise<void>
Displays the given places on the map.
Parameters
- places: ShownPlaces
 Place data to display. Can be a single Place, array of Places, or a Places FeatureCollection.
Returns Promise<void>
Remarks
Behavior:
- Replaces any previously shown places, and never merges with them
- Drops the event states of the places it replaces, even of a place shown again under the same id: an event state lives on the shown feature, so re-select with putEventState by id. Places that carry properties.eventState, such as getShown().places, keep theirs
- Drops the shown connections (see PlaceConnectionDisplay)
- Applies current module styling configuration
- Automatically generates labels if label config is set
- Waits for module to be ready before displaying
Data Sources:
- TomTom Search API results
- Custom place objects matching the Place interface
- GeoJSON Point features
ShownPlaces names the places services whose results are not places, and what shows them.
Example
Display search results:
```
import { discoverPlaces } from '@tomtom-org/maps-sdk/services';

const results = await discoverPlaces({ query: 'coffee' });
await placesModule.show(results);
```
Example
Display single place:
```
await placesModule.show({
 type: 'Feature',
 geometry: { type: 'Point', coordinates: [4.9041, 52.3676] },
 properties: {
 address: { freeformAddress: 'Amsterdam' },
 poi: { name: 'Amsterdam Central' }
 }
});
```
Example
Display multiple places:
```
await placesModule.show([place1, place2, place3]);
```

showConnections

showConnections(connections: PlaceConnectionDisplay[]): Promise<void>
Displays connection lines between pairs of places on the map.
Parameters
- connections: PlaceConnectionDisplay[]
 List of connections to render. Each connection has a from and to endpoint, expressed either as a Place or as the id of a place currently shown by this module.
Returns Promise<void>
Remarks
Behavior:
- Replaces any previously shown connections
- Connections whose id reference cannot be resolved against the currently shown places are silently skipped
- When PlaceConnectionsConfig.label is set on the module config, the returned string is rendered as a label along each line, slightly offset to the side. Without a label function, no label is shown.
- Calling show() or clear() pre-clears connections, since their endpoints may no longer be on the map.
Example
```
const places = await PlacesModule.create(map, {
 connections: {
 label: (c) => `${c.distanceMeters} m`
 }
});
await places.show([station, ...cafes]);
await places.showConnections(
 cafes.features.map((cafe) => ({
 from: station.id,
 to: cafe.id,
 distanceMeters: Math.round(cafe.properties.dist ?? 0),
 })),
);
```

updateConfig

updateConfig(
partial: PlacesModuleConfig,
): void
Changes part of the configuration and keeps the rest, redrawing the places already shown.
Type Parameters
- P extends CommonPlaceProps = CommonPlaceProps
 The place shape the label.title, icon.mapping and extraFeatureProps callbacks expect, as with PlacesModule.create.
Parameters
- partial: PlacesModuleConfig
Returns void
Example
```
places.updateConfig({ markerType: 'base-map' });
places.updateConfig({ icon: { categoryIcons: [{ id: 'RESTAURANT', image: '/icons/food.png' }] } });
places.updateConfig<MyPlaceProps>({ extraFeatureProps: { brand: (place) => place.properties.brand } });
```
Overrides AbstractDataOwnedMapModule.updateConfig

`Protected`waitUntilModuleReady

waitUntilModuleReady(): Promise<void>

Returns Promise<void>

Inherited from AbstractDataOwnedMapModule.waitUntilModuleReady

`Static`create

create(
tomtomMap: TomTomMap,
config?: PlacesModuleConfig,
): Promise<PlacesModule>
Creates a new module instance on the given map, waiting until the map is ready first.

PlacesModule owns the sources, layers and images it adds, all suffixed per instance. Every call therefore returns a new, independent instance, and stacking several of them on one map is a supported thing to do.
Type Parameters
- P extends CommonPlaceProps = CommonPlaceProps
Parameters
- tomtomMap: TomTomMap
 The TomTomMap instance.
- Optionalconfig: PlacesModuleConfig
 The module optional configuration
Returns Promise<PlacesModule>
Returns a promise with a new instance of this module

Class PlacesModule

Remarks

Example

See

Hierarchy (View Summary)

Index

Accessors

Methods

Accessors

events

Returns PlacesEvents

sourceAndLayerIDs

Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

Remarks

Example

Methods

applyConfig

Type Parameters

Parameters

Returns void

Example

cleanEventState

Parameters

Returns void

Example

cleanEventStates

Parameters

Returns void

Example

clear

Returns Promise<void>

Remarks

Example

clearConnections

Returns Promise<void>

Example

getConfig

Returns NonNullable<PlacesModuleConfig> | undefined

Remarks

Example

See

getEventStates

Returns EventStateIds

Remarks

Example

getShown

Returns { connections: PlaceConnectionDisplay[]; places: Places<DisplayPlaceProps> }

Remarks

Example

isVisible

Returns boolean

putEventState

Parameters

Returns void

Remarks

Example

resetConfig

Returns void

Remarks

Example

See

setVisible

Parameters

Returns void

Remarks

Example

show

Parameters

Returns Promise<void>

Remarks

Example

Example

Example

showConnections

Parameters

Returns Promise<void>

Remarks

Example

updateConfig

Type Parameters

`Protected`waitUntilModuleReady

`Static`create