Class GeometriesModule

Geometries Module for displaying polygon areas with custom styling on the map.

This module enables visualization of geographic areas (polygons) with customizable colors, borders, and labels. Ideal for displaying search results, administrative boundaries, service areas, or any polygon-based geographic data.

Remarks

Features:

Display single or multiple polygon geometries
Customizable fill colors and opacity
Configurable borders (color, width, opacity)
Optional text labels for geometries
Support for data-driven styling via MapLibre expressions
Layer ordering control
Event handling for user interactions

Data Format:

Accepts GeoJSON Polygon and MultiPolygon features
Supports FeatureCollection for multiple geometries
Compatible with TomTom Search API geometry results

Styling:

Use predefined color palettes or custom colors
Apply MapLibre expressions for dynamic styling
Per-feature styling via feature properties

Example

Basic usage:

import { GeometriesModule } from '@tomtom-org/maps-sdk/map';

// Initialize module
const geometriesModule = await GeometriesModule.create(map);

// Display a polygon
await geometriesModule.show({
  type: 'Feature',
  geometry: {
    type: 'Polygon',
    coordinates: [[[4.88, 52.37], [4.89, 52.37], [4.89, 52.38], [4.88, 52.38], [4.88, 52.37]]]
  },
  properties: {
    title: 'Area of Interest'
  }
});

Example

Custom styling:

const geometriesModule = await GeometriesModule.create(map, {
  fill: { color: '#FF5733', opacity: 0.3 },
  line: { color: '#C70039', width: 3 },
  label: {
    text: ['get', 'name']
  }
});

await geometriesModule.show(polygonFeatures);

Example

Multiple geometries with different colors:

await geometriesModule.show({
  type: 'FeatureCollection',
  features: [
    {
      type: 'Feature',
      geometry: { type: 'Polygon', coordinates: [...] },
      properties: { color: '#FF0000', title: 'Red Zone' }
    },
    {
      type: 'Feature',
      geometry: { type: 'Polygon', coordinates: [...] },
      properties: { color: '#00FF00', title: 'Green Zone' }
    }
  ]
});

Example

Event handling:

geometriesModule.events.on('click', (feature, lngLat) => {
  console.log('Clicked geometry:', feature.properties.title);
  console.log('At coordinates:', lngLat);
});

geometriesModule.events.on('hover', (feature) => {
  showTooltip(feature.properties.title);
});

See

Geometries Guide

Hierarchy (View Summary)

AbstractDataOwnedMapModule<GeometrySourcesWithLayers, GeometriesModuleConfig>
- GeometriesModule

Index

Accessors

events sourceAndLayerIDs

Methods

applyConfig applyTextConfig clear getConfig getShown isVisible moveBeforeLayer resetConfig setVisible show updateConfig waitUntilModuleReady create

Accessors

events

get events(): GeometriesEvents
Gets the events interface for handling user interactions with geometries.

Returns GeometriesEvents
The module's events, with on / off for handlers and where for scoping.
Remarks
Supported Events:
- click: User clicks on a geometry
- contextmenu: User right-clicks on a geometry
- hover: Mouse enters a geometry
- long-hover: Mouse hovers over geometry for extended time
Event Features:
- Receive the original feature data passed to show()
- Access feature properties and geometry
- Get click/hover coordinates
Example
Basic event handling:
```
geometries.events.on('click', (feature, lngLat) => {
  console.log('Clicked:', feature.properties);
  console.log('Location:', lngLat);
});
```
Example
Multiple handlers:
```
// Highlight on hover
geometries.events.on('hover', (feature) => {
  highlightGeometry(feature.id);
});

// Show details on click
geometries.events.on('click', (feature) => {
  showDetailPanel(feature.properties);
});

// Context menu
geometries.events.on('contextmenu', (feature, lngLat) => {
  showContextMenu(lngLat, feature);
});
```

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: GeometriesModuleConfig | 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: GeometriesModuleConfig | 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

applyTextConfig

applyTextConfig(label: GeometryLabel): void
Updates the label at the center of each displayed geometry: its text and styling.
Parameters
- label: GeometryLabel
  New label configuration.
Returns void
Remarks
Configuration:
- text: MapLibre expression for label text content
- size, color, haloColor, haloWidth, opacity, font: label styling
- Changes apply to currently shown and future geometries
Example
```
// Show feature property as label
geometries.applyTextConfig({
  text: ['get', 'name']
});

// Conditional labels, in white
geometries.applyTextConfig({
  text: [
    'case',
    ['has', 'label'],
    ['get', 'label'],
    ['get', 'title']
  ],
  color: '#FFFFFF',
});
```

clear

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

Returns Promise<void>
Remarks
- Clears both geometry layers and labels
- Does not reset styling configuration
- Module remains initialized and ready for new data
Example
```
// Clear displayed geometries
await geometries.clear();

// Show new geometries
await geometries.show(newGeometries);
```

getConfig

getConfig(): NonNullable<GeometriesModuleConfig> | 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<GeometriesModuleConfig> | 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(): {
geometry: PolygonFeatures;
geometryLabel: FeatureCollection<Point, GeoJsonProperties>;
}
Returns the currently shown geometries.

Returns {
geometry: PolygonFeatures;
geometryLabel: FeatureCollection<Point, GeoJsonProperties>;
}
The geometries currently displayed on the map.
Remarks
Returns the exact data that was passed to the show() method.
Example
```
const shown = geometriesModule.getShown();
console.log(`Geometries: ${shown.geometry.features.length}`);
```

isVisible

isVisible(): boolean

Whether the module is set to be shown (GeometriesModuleConfig.visible). A shown module with no geometries draws nothing.

Returns boolean

moveBeforeLayer

moveBeforeLayer(layerConfig: GeometryBeforeLayerConfig): void
Positions the geometry layers relative to other map layers.
Parameters
- layerConfig: GeometryBeforeLayerConfig
  Layer positioning. A single BeforeLayerConfig ('top' or a layer id) moves all geometry layers together; the record form ({ all?, fill?, line? }) positions the fill and border independently, leaving a part it names no target for where it is.
  
  Available Layer IDs: the keys of mapStyleLayerIDs.
Returns void
Example
```
// Place all geometry layers below labels
geometries.moveBeforeLayer('lowestLabel');

// Fill below the road network, border on top
geometries.moveBeforeLayer({ fill: 'lowestRoadLine', line: 'top' });
```

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: fills, borders, center labels and border labels.
Parameters
- visible: boolean
Returns void
Remarks
show() and clear() never change it: a hidden module keeps its data and draws it again on setVisible(true).
Example
```
geometries.setVisible(false);
await geometries.show(areas); // stays hidden
geometries.setVisible(true);
```

show

show(geometries: PolygonFeatures): Promise<void>
Displays the given polygon geometries on the map.
Parameters
- geometries: PolygonFeatures
  Polygon features to display. Can be a single Feature, array of Features, or a FeatureCollection.
Returns Promise<void>
Remarks
Behavior:
- Replaces any previously shown geometries
- Applies current module styling configuration
- Waits for module to be ready before displaying
- Automatically handles both Polygon and MultiPolygon types
Feature Properties:
- title: Used for labels if label is not set
- color: Override fill color per feature
- fillStyle: Override the module's fillStyle per feature
- Custom properties accessible in styling expressions
Example
Single polygon:
```
await geometries.show({
  type: 'Feature',
  geometry: {
    type: 'Polygon',
    coordinates: [[[4.88, 52.37], [4.89, 52.37], [4.89, 52.38], [4.88, 52.37]]]
  },
  properties: {
    title: 'Amsterdam Center',
    color: '#FF5733'
  }
});
```
Example
Multiple polygons:
```
await geometries.show({
  type: 'FeatureCollection',
  features: [
    { type: 'Feature', geometry: {...}, properties: {...} },
    { type: 'Feature', geometry: {...}, properties: {...} }
  ]
});
```
Example
From a place's geometry:
```
import { geocodeOne, geometryData } from '@tomtom-org/maps-sdk/services';

const amsterdam = await geocodeOne('Amsterdam');
await geometries.show(await geometryData({ geometries: [amsterdam] }));
```

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?: GeometriesModuleConfig,
): Promise<GeometriesModule>
Make sure the map is ready before create an instance of the module and any other interaction with the map
Parameters
- tomtomMap: TomTomMap
  The TomTomMap instance.
- Optionalconfig: GeometriesModuleConfig
  The module optional configuration
Returns Promise<GeometriesModule>
Returns a promise with a new instance of this module
Remarks
Configuration Options:
- color: Base colour for fill and border
- fill: Fill color and opacity
- line: Border/outline styling
- label: Center label text and styling
- beforeLayerConfig: Layer ordering — a single target, or { all, fill, line } to split them
Multiple Instances: GeometriesModule owns the sources, layers and images it adds, all suffixed per instance. Every call therefore returns a new, independent instance, so you can put several on the same map, each managing a different set of geometries with different styles.
Example
Default initialization:
```
const geometriesModule = await GeometriesModule.create(map);
```
Example
With custom styling:
```
const geometriesModule = await GeometriesModule.create(map, {
  fill: { color: 'blue', opacity: 0.25 },
  line: { color: 'darkblue', width: 2, opacity: 0.8 },
  label: {
    text: ['get', 'title']
  },
  beforeLayerConfig: 'top'
});
```
Example
Data-driven styling:
```
const geometriesModule = await GeometriesModule.create(map, {
  fill: {
    // Color based on feature properties
    color: [
      'match',
      ['get', 'type'],
      'residential', '#FFEB3B',
      'commercial', '#2196F3',
      'industrial', '#9E9E9E',
      '#E0E0E0' // default
    ],
    opacity: 0.4
  }
});
```

Class GeometriesModule

Remarks

Example

Example

Example

Example

See

Hierarchy (View Summary)

Index

Accessors

Methods

Accessors

events

Returns GeometriesEvents

Remarks

Example

Example

sourceAndLayerIDs

Returns Record<keyof SOURCES_WITH_LAYERS, SourceWithLayerIDs>

Remarks

Example

Methods

applyConfig

Parameters

Returns void

Remarks

Example

See

applyTextConfig

Parameters

Returns void

Remarks

Example

clear

Returns Promise<void>

Remarks

Example

getConfig

Returns NonNullable<GeometriesModuleConfig> | undefined

Remarks

Example

See

getShown

Returns { geometry: PolygonFeatures; geometryLabel: FeatureCollection<Point, GeoJsonProperties>;}

Remarks

Example

isVisible

Returns boolean

moveBeforeLayer

Parameters

Returns void

Example

resetConfig

Returns void

Remarks

Example

See

setVisible

Parameters

Returns void

Remarks

Example

show

Parameters

Returns Promise<void>

Remarks

Example

Example

Example

updateConfig

Parameters

Returns void

Example

See

ProtectedwaitUntilModuleReady

Returns Promise<void>

Staticcreate

Parameters

Returns Promise<GeometriesModule>

Remarks

Returns {
geometry: PolygonFeatures;
geometryLabel: FeatureCollection<Point, GeoJsonProperties>;
}

`Protected`waitUntilModuleReady

`Static`create