TomTom Maps SDK for JavaScript
This is the documentation of version 0.47.7. Go to the latest version, 1.0.0-rc.5.

Geometry Module

The Geometry Module in the TomTom Maps SDK enables displaying and visualizing geographic shapes and polygons on maps. This module provides comprehensive functionality for rendering complex geometries, administrative boundaries, and custom geographic data with customizable styling.

Purpose and Functionality

The Geometry Module serves as the primary interface for:

Core Concepts

Geometry Data Types

The module supports various types of geographic geometries:

Supported Geometry Types:

Data Sources

Geometries can come from multiple sources:

Basic Geometry Display

Initializing Geometry Module

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap, GeometriesModule } from '@tomtom-org/maps-sdk/map';

// Configure SDK and create map
TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });
const map = new TomTomMap({ mapLibre: { container: 'map' } });

// Initialize geometry module with default styling
const geometryModule = await GeometriesModule.get(map);

Displaying Administrative Boundaries

import { geocode, geometryData } from '@tomtom-org/maps-sdk/services';

// Get geometry for a specific place
const place = (await geocode({ query: 'Amsterdam, Netherlands' })).features[0];
const geometryResponse = await geometryData({ geometries: [place] });

// Display the geometry on the map
geometryModule.show(geometryResponse);

Custom Styling Configuration

// Initialize with custom styling
const geometryModule = await GeometriesModule.get(map, {
    colorConfig: {
        fillColor: '#007cbf',      // Fill color for polygons
        fillOpacity: 0.3           // Fill transparency
    },
    lineConfig: {
        lineColor: '#005a8b',      // Border color
        lineWidth: 2,              // Border width
        lineOpacity: 0.8           // Border transparency
    },
    beforeLayerConfig: 'road-labels' // Layer positioning
});

Advanced Geometry Features

Multiple Geometry Layers

// Create multiple geometry modules for different data sets
const countryGeometryModule = await GeometriesModule.get(map, {
    colorConfig: { fillColor: '#ff6b6b', fillOpacity: 0.2 },
    lineConfig: { lineColor: '#ff0000', lineWidth: 3 }
});

const cityGeometryModule = await GeometriesModule.get(map, {
    colorConfig: { fillColor: '#4ecdc4', fillOpacity: 0.4 },
    lineConfig: { lineColor: '#00a896', lineWidth: 2 }
});

// Display different geometry types
countryGeometryModule.show(countryBoundaries);
cityGeometryModule.show(cityBoundaries);

Dynamic Geometry Management

// Add and remove geometries dynamically
const geometryModule = await GeometriesModule.get(map);

// Show new geometry data
function displayGeometry(newGeometryData) {
    geometryModule.clear(); // Clear existing geometries
    geometryModule.show(newGeometryData);
}

// Toggle geometry visibility
let geometryVisible = true;
function toggleGeometry() {
    if (geometryVisible) {
        geometryModule.clear();
    } else {
        geometryModule.show(currentGeometryData);
    }
    geometryVisible = !geometryVisible;
}

Layer Positioning and Styling

// Advanced styling with layer control
const geometryModule = await GeometriesModule.get(map, {
    beforeLayerConfig: 'road-labels',  // Position below road labels
    colorConfig: {
        fillColor: '#87CEEB',
        fillOpacity: 0.5
    },
    lineConfig: {
        lineColor: '#4682B4',
        lineWidth: 1.5,
        lineOpacity: 1
    }
});

Themed Geometry Display

The SDK supports three visual themes for polygon display:

Theme Effect
'filled' Semi-transparent fill (default)
'outline' Transparent fill with a thick border
'inverted' Semi-transparent area outside the polygon

Setting theme at config level

The simplest way to apply a theme is via the theme option in GeometriesModuleConfig:

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

// Highlight "rest of the world" outside a country
const module = await GeometriesModule.get(map, {
    theme: 'inverted',
    colorConfig: { fillColor: 'black', fillOpacity: 0.5 },
});
module.show(countryGeometry);

Individual features can override the config-level theme by setting theme in their own properties.

Using themedGeometryConfig for mixed themes

When features in the same layer need different themes, use themedGeometryConfig(palette?). It returns a config with MapLibre expressions that read each feature's theme property and apply the appropriate style:

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

const module = await GeometriesModule.get(map, themedGeometryConfig('blues'));

// Features carry their own theme — styling adapts per feature
module.show({
    type: 'FeatureCollection',
    features: [
        { ...featureA, properties: { theme: 'filled', title: 'Zone A' } },
        { ...featureB, properties: { theme: 'outline', title: 'Zone B' } },
    ],
});

A center label is shown for each polygon whenever the feature carries a title property.

Color palettes

Both themedGeometryConfig and reachableRangeGeometryConfig accept a named palette as their first argument (defaulting to 'fadedRainbow'). The palette controls the fill colors assigned to successive polygon rings.

Available palettes: warm, browns, cold, fadedBlues, blues, greens, fadedGreenToBlue, blueToRed, greenToYellow, pastel, retro, contrastRetro, fadedRainbow, pastelRainbow.

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

// Use the 'retro' palette with filled theme (default)
const config = themedGeometryConfig('retro');

// Palette names are typed as ColorPaletteOptions

For reachable ranges specifically, use reachableRangeGeometryConfig which builds on themedGeometryConfig and additionally wires up label generation and the inverted-theme donut transform automatically. See Reachable Ranges.

Multiple Module Instances

You can create multiple independent instances of the Geometry module, each with its own configuration and styling. This is useful for displaying different geometry layers with distinct visual styles.

// Create separate instances for different geometry types
const countryBorders = await GeometriesModule.get(map, {
    colorConfig: { fillColor: '#E74C3C', fillOpacity: 0.2 },
    lineConfig: { lineColor: '#C0392B', lineWidth: 3 }
});

const cityBounds = await GeometriesModule.get(map, {
    colorConfig: { fillColor: '#3498DB', fillOpacity: 0.3 },
    lineConfig: { lineColor: '#2980B9', lineWidth: 2 }
});

// Each instance manages its own geometries independently
countryBorders.show(countryData);
cityBounds.show(cityData);

Reading Shown Data

Use getShown() to retrieve the geometries currently displayed on the map. This returns the exact data previously passed to show():

const shown = geometriesModule.getShown();
console.log(`Geometries: ${shown.geometry.features.length}`);

Related Guides and Examples

Services Integration

Related Examples

Related Map Modules