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.enabled 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: { enabled: 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: { enabled: 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.

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: PlacesModuleConfig | undefined
  The configuration object to apply to the module. Pass undefined to reset the configuration to default values.
Returns void
Remarks
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.

The given configuration replaces the current one rather than being merged into it. To change one part of it, use updateConfig.
Example
```
// Apply a new configuration
myModule.applyConfig({ visible: true, opacity: 0.8 });

// Reset to default configuration
myModule.applyConfig(undefined);
```
See
- resetConfig for a convenience method to reset configuration
- getConfig to retrieve the current configuration
Inherited from AbstractDataOwnedMapModule.applyConfig

applyExtraFeatureProps

applyExtraFeatureProps(
 extraFeatureProps: NonNullable<
 PlacesModuleConfig["extraFeatureProps"],
 >,
): void
Applies additional feature properties to displayed places.
Type Parameters
- P extends CommonPlaceProps = CommonPlaceProps
Parameters
- extraFeatureProps: NonNullable<PlacesModuleConfig["extraFeatureProps"]>
 Object mapping property names to values or functions.
Returns void
Remarks
Useful for adding computed properties or metadata for styling/filtering.
Example
```
placesModule.applyExtraFeatureProps({
 category: (place) => place.properties.poi?.localizedCategories?.[0],
 brand: (place) => place.properties.poi?.brands?.[0] ?? '',
 isOpen: true
});
```

applyIconConfig

applyIconConfig(
iconConfig: PlaceIconConfig,
): void
Updates the icon configuration for displayed places.
Type Parameters
- P extends CommonPlaceProps = CommonPlaceProps
Parameters
- iconConfig: PlaceIconConfig
 New icon configuration settings.
Returns void
Remarks
- Changes apply immediately to currently shown places
- Custom icons are loaded if not already in style
- Other configuration properties remain unchanged
Example
```
placesModule.applyIconConfig({
 categoryIcons: [
 { id: 'RESTAURANT', image: '/icons/food.png' }
 ]
});
```

applyLabelConfig

applyLabelConfig(
label: PlaceLabelConfig,
): void
Replaces the label configuration of the displayed places.
Type Parameters
- P extends CommonPlaceProps = CommonPlaceProps
Parameters
- label: PlaceLabelConfig
Returns void
Remarks
Supports both functions and MapLibre expressions for dynamic text.
Example
```
// Use function
placesModule.applyLabelConfig({
 title: (place) => place.properties.poi?.name || 'Unknown'
});

// Use MapLibre expression
placesModule.applyLabelConfig({
 title: ['get', 'title'],
 size: 14,
 color: '#333'
});
```

applyMarkerType

applyMarkerType(
markerType: "pin" | "circle-icon" | "base-map" | "pin-clustered",
): void
Changes the kind of marker places are drawn with.
Parameters
- markerType: "pin" | "circle-icon" | "base-map" | "pin-clustered"
Returns void

Remarks
Redraws the places already shown, and leaves the rest of the configuration as it is.

cleanEventState

cleanEventState(options: CleanEventStateOptions): void
Removes an event state from a specific place.
Parameters
- options: CleanEventStateOptions
  Configuration for which event state to remove.
Returns void
Example
```
placesModule.cleanEventState({ index: 0 });
```

cleanEventStates

cleanEventStates(options?: CleanEventStatesOptions): void
Removes event states from multiple places.
Parameters
- Optionaloptions: CleanEventStatesOptions
  Optional filter for which states to remove.
Returns void
Example
```
// Remove all event states
placesModule.cleanEventStates();

// Remove only hover states
placesModule.cleanEventStates({ states: ['hover'] });
```

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, 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
```
See
- applyConfig to modify the configuration
- resetConfig to clear the configuration
Inherited from AbstractDataOwnedMapModule.getConfig

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
Programmatically sets an event state on a specific place.
Parameters
- options: PutEventStateOptions
  Configuration for the event state to apply.
Returns void
Remarks
Use this to make places appear clicked or hovered programmatically.

The state lives on the shown place: a style change, applyConfig and a marker type change keep it, while show of new results, clear and a setStyle with resetState drop it, whatever the ids.
Example
```
// Make first place appear clicked
placesModule.putEventState({
  index: 0,
  state: 'click',
  mode: 'put'
});
```

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, opacity: 0.5 });

// 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: Partial<NonNullable<CFG>>): void
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 nested object that was there — and the result is applied with applyConfig. This is the same on every module, whatever its applyConfig does with a whole configuration.
Parameters
- partial: Partial<NonNullable<CFG>>
 The properties to change.
Returns void
Example
```
routing.applyConfig({ displayUnits: 'imperial', color: '#0a3653' });
routing.updateConfig({ color: '#c2185b' }); // displayUnits stays imperial
```
See
applyConfig to apply a whole configuration
Inherited from 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

Parameters

Returns void

Remarks

Example

See

applyExtraFeatureProps

Type Parameters

Parameters

Returns void

Remarks

Example

applyIconConfig

Type Parameters

Parameters

Returns void

Remarks

Example

applyLabelConfig

Type Parameters

Parameters

Returns void

Remarks

Example

applyMarkerType

Parameters

Returns void

Remarks

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

getShown

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

Remarks

Example

isVisible

Returns boolean

putEventState

Parameters

Returns void

Remarks

Example

resetConfig

Returns void

Remarks

Example

See

`Protected`waitUntilModuleReady

`Static`create