Class PlacesModule

Base class for the map modules that add and own their own GeoJSON sources, layers and images: places, routes, geometries, the traffic overlays and bring-your-own-data.

Remarks

The module owns the data it draws. Its generated IDs therefore carry a per-instance suffix (see instanceIndex), and the module is safely multi-instance: every create(map, config?) call returns another module with its own sources and layers.

Owning the data brings the duty this class states: a clean style switch must forget the data the module remembers having shown, through discardShownData.

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.

Unless a module documents otherwise, 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],
 rating: (place) => place.properties.poi?.rating || 0,
 isOpen: true
});
```

applyIconConfig

applyIconConfig(iconConfig: PlaceIconConfig): void
Updates the icon configuration for displayed places.
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: [
    { category: 'RESTAURANT', id: 'restaurant-icon', image: '/icons/food.png' }
  ]
});
```

applyTextConfig

applyTextConfig(textConfig: PlaceTextConfig): void
Updates the text/label configuration for displayed places.
Parameters
- textConfig: PlaceTextConfig
  New text configuration settings.
Returns void
Remarks
Supports both functions and MapLibre expressions for dynamic text.
Example
```
// Use function
placesModule.applyTextConfig({
  field: (place) => place.properties.poi?.name || 'Unknown'
});

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

applyTheme

applyTheme(theme: "pin" | "circle-icon" | "base-map" | "pin-clustered"): void
Updates the visual theme for displayed places.
Parameters
- theme: "pin" | "circle-icon" | "base-map" | "pin-clustered"
  The theme style to apply to place markers.
Returns void
Remarks
Available Themes:
- pin: Traditional teardrop-shaped map pins
- circle-icon: Simple circular markers (previously named circle)
- base-map: Mimics the map's built-in POI layer style with category icons (combines main, selected, and micro). For micro-only rendering, hide the main layer via layers.main.layout.visibility = 'none'.
Changes apply immediately to all currently shown places. Other configuration properties (icon config, text config) remain unchanged.
Example
```
// Switch to pin markers
placesModule.applyTheme('pin');

// Use simple circles
placesModule.applyTheme('circle-icon');

// Match map's POI style (ideal to blend in)
placesModule.applyTheme('base-map');
```

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
- 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
Returns the exact data that was passed to the show() method.
Example
```
const shown = placesModule.getShown();
console.log(`Showing ${shown.places.features.length} places`);
```

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.
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

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
- Applies current module styling configuration
- Automatically generates labels if text 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
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', theme: { mainColor: '#0a3653' } });
routing.updateConfig({ theme: { mainColor: '#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

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

Parameters

Returns void

Remarks

Example

applyTextConfig

Parameters

Returns void

Remarks

Example

applyTheme

Parameters

Returns void

Remarks

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

getShown

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

Remarks

Example

putEventState

Parameters

Returns void

Remarks

Example

resetConfig

Returns void

Remarks

Example

See

show

Parameters

Returns Promise<void>

Remarks

Example

`Protected`waitUntilModuleReady

`Static`create