TomTom Maps for JavaScript
    Preparing search index...

    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.

    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

    Basic usage:

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

    // Initialize module
    const geometriesModule = await GeometriesModule.get(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'
      }
    });

    Custom styling:

    const geometriesModule = await GeometriesModule.get(map, {
      colorConfig: {
        fillColor: '#FF5733',
        fillOpacity: 0.3
      },
      lineConfig: {
        lineColor: '#C70039',
        lineWidth: 3
      },
      textConfig: {
        textField: ['get', 'name']
      }
    });

    await geometriesModule.show(polygonFeatures);

    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' }
        }
      ]
    });

    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);
    });

    Geometries Guide

    Hierarchy (View Summary)

    Index

    Accessors

    events sourceAndLayerIDs

    Methods

    applyConfig applyTextConfig clear getConfig moveBeforeLayer resetConfig show waitUntilModuleReady get

    Accessors

    • Gets the events interface for handling user interactions with geometries.

      Returns EventsModule<MapGeoJSONFeature>

      An EventsModule instance for registering event handlers.

      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

      Basic event handling:

      geometries.events.on('click', (feature, lngLat) => {
        console.log('Clicked:', feature.properties);
        console.log('Location:', lngLat);
      });

      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);
      });
    • 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.

      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
      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');
      });

    Methods

    • 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

      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.

      // Apply a new configuration
      myModule.applyConfig({ visible: true, opacity: 0.8 });

      // Reset to default configuration
      myModule.applyConfig(undefined);
      • resetConfig for a convenience method to reset configuration
      • getConfig to retrieve the current configuration

    • Updates the text/label configuration for displayed geometries.

      Parameters

      Returns void

      Configuration:

      • textField: MapLibre expression for label text content
      • Supports dynamic text based on feature properties
      • Changes apply to currently shown and future geometries
      // Show feature property as label
      geometries.applyTextConfig({
        textField: ['get', 'name']
      });

      // Conditional labels
      geometries.applyTextConfig({
        textField: [
          'case',
          ['has', 'label'],
          ['get', 'label'],
          ['get', 'title']
        ]
      });

    • Removes all geometries from the map.

      Returns Promise<void>

      • Clears both geometry layers and labels
      • Does not reset styling configuration
      • Module remains initialized and ready for new data
      // Clear displayed geometries
      await geometries.clear();

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

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

      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.

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

    • Positions the geometry layers relative to other map layers.

      Parameters

      • layerConfig: GeometryBeforeLayerConfig

        Layer positioning configuration. Can be 'top' to place above all layers, or a specific layer ID.

      Returns void

      Use Cases:

      • Place geometries above base map but below labels
      • Ensure geometries appear above/below specific features
      • Control visual hierarchy of multiple data layers

      Available Layer IDs: Use predefined layer IDs from mapStyleLayerIDs or custom layer IDs.

      import { mapStyleLayerIDs } from '@tomtom-international/maps-sdk-js/map';

      // Place below labels
      geometries.moveBeforeLayer(mapStyleLayerIDs.lowestLabel);

      // Place on top
      geometries.moveBeforeLayer('top');

    • 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

      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.

      // Apply some configuration
      myModule.applyConfig({ visible: true, opacity: 0.5 });

      // Later, reset to defaults
      myModule.resetConfig();
      • applyConfig to apply a new configuration
      • getConfig to retrieve the current configuration before resetting

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

      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 text config is set
      • color: Override fill color per feature
      • Custom properties accessible in styling expressions

      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'
        }
      });

      Multiple polygons:

      await geometries.show({
        type: 'FeatureCollection',
        features: [
          { type: 'Feature', geometry: {...}, properties: {...} },
          { type: 'Feature', geometry: {...}, properties: {...} }
        ]
      });

      From search API response:

      import { search } from '@tomtom-international/maps-sdk-js/services';

      const result = await search.geometrySearch({
        query: 'Amsterdam',
        geometryList: [{ type: 'CIRCLE', position: [52.37, 4.89], radius: 5000 }]
      });

      if (result.results[0].dataSources?.geometry) {
        await geometries.show(result.results[0].dataSources.geometry);
      }

    • Make sure the map is ready before create an instance of the module and any other interaction with the map

      Parameters

      Returns Promise<GeometriesModule>

      Returns a promise with a new instance of this module

      Configuration Options:

      • colorConfig: Fill color and opacity settings
      • lineConfig: Border/outline styling
      • textConfig: Label display configuration
      • beforeLayerConfig: Layer ordering (place above/below other layers)

      Multiple Instances: You can create multiple GeometriesModule instances on the same map, each managing different sets of geometries with different styles.

      Default initialization:

      const geometriesModule = await GeometriesModule.get(map);

      With custom styling:

      const geometriesModule = await GeometriesModule.get(map, {
        colorConfig: {
          fillColor: 'blue',
          fillOpacity: 0.25
        },
        lineConfig: {
          lineColor: 'darkblue',
          lineWidth: 2,
          lineOpacity: 0.8
        },
        textConfig: {
          textField: ['get', 'title']
        },
        beforeLayerConfig: 'top'
      });

      Data-driven styling:

      const geometriesModule = await GeometriesModule.get(map, {
        colorConfig: {
          // Color based on feature properties
          fillColor: [
            'match',
            ['get', 'type'],
            'residential', '#FFEB3B',
            'commercial', '#2196F3',
            'industrial', '#9E9E9E',
            '#E0E0E0' // default
          ],
          fillOpacity: 0.4
        }
      });

    Settings

    Member Visibility

    On This Page

    Accessors
    Methods