TomTom Maps SDK for JavaScript
This is the documentation of version 0.59.0. 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.

What this module owns: the fills, outlines and labels it draws, and how they look — the color, fill, line, label, fill style and palette configuration below. It never restyles the base map underneath, which belongs to the Styling module, and styling knobs never touch geometry layers: geometries given no colour read the map's accent as their default. See Who owns what.

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.create(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
await geometryModule.show(geometryResponse);

Custom styling configuration

One top-level color sets the fill and the border together:

const geometryModule = await GeometriesModule.create(map, { color: '#E63312' });

The colours resolve in this order, first match wins:

Part Precedence
Fill a feature's own color property → fill.color → color → the map's accent → the default
Border line.color → a feature's own color property → fill.color → color → the map's accent → the default

The accent applies when a theme sets one. The default adapts to the map style: navy #0A3653 on light styles, sky blue #5FA8D8 on dark ones. With fillStyle: 'outline', the border ends on a neutral grey instead of the accent or the default.

Fill and border are configured independently via fill and line. Each exposes concise curated fields for the common cases — fill: { color, opacity } and line: { color, width, opacity }:

// Initialize with custom styling
const geometryModule = await GeometriesModule.create(map, {
    fill: {
        color: '#007cbf',   // Fill color for polygons
        opacity: 0.3        // Fill transparency
    },
    line: {
        color: '#005a8b',   // Border color
        width: 2,           // Border width
        opacity: 0.8        // Border transparency
    },
    beforeLayerConfig: 'lowestLabel' // Layer positioning (below all labels)
});

For border properties the curated fields don't cover, the line.layer escape hatch accepts a partial MapLibre LineLayerSpecification (without id/source) and can set any line property — an inset/outset border (line-offset), a soft glow (line-blur), a dashed border (line-dasharray), a hollow casing (line-gap-width), line-cap, line-join, line-pattern, and more. The curated color/width/opacity fields take precedence over the same paint property set via layer:

const geometryModule = await GeometriesModule.create(map, {
    line: {
        color: '#00A65E',
        width: 2,
        layer: {
            paint: {
                'line-offset': 2,          // Lateral offset in pixels (inset/outset border)
                'line-blur': 4,            // Edge blur in pixels (glow/halo effect)
                'line-dasharray': [2, 2],  // Dash pattern in line-width units ([dash, gap, …])
                'line-gap-width': 3        // Hollow casing
            },
            layout: { 'line-cap': 'round' }
        }
    }
});

Advanced geometry features

Multiple geometry layers

// Create multiple geometry modules for different data sets
const countryGeometryModule = await GeometriesModule.create(map, {
    fill: { color: '#ff6b6b', opacity: 0.2 },
    line: { color: '#ff0000', width: 3 }
});

const cityGeometryModule = await GeometriesModule.create(map, {
    fill: { color: '#4ecdc4', opacity: 0.4 },
    line: { color: '#00a896', width: 2 }
});

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

Dynamic geometry management

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

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

Showing and hiding

setVisible hides and shows the fills, borders, center labels and border labels together, and visible: false at creation starts the module hidden. show() and clear() never change it: geometries shown while hidden appear on setVisible(true), and the state survives a style change.

// Toggle geometry visibility, keeping the data
function toggleGeometry() {
    geometryModule.setVisible(!geometryModule.isVisible());
}

Layer positioning and styling

A single beforeLayerConfig positions all geometry layers together. To place the fill and border at different points in the stack, pass the object form { fill, line } (or set beforeLayerConfig inside the fill / line sections):

const geometryModule = await GeometriesModule.create(map, {
    fill: { color: '#87CEEB', opacity: 0.5 },
    line: { color: '#4682B4', width: 1.5 },
    // Fill slips below the road network while the border stays above the labels
    beforeLayerConfig: { fill: 'lowestRoadLine', line: 'lowestLabel' }
});

Labels

A center label is shown for each polygon whenever the feature carries a title property. label replaces its text with a MapLibre expression and styles it; lineLabel repeats the title along the border, and is drawn only when set ({} for the defaults). Both take the same styling fields as every module's labels — size, color, haloColor, haloWidth, opacity and font:

const module = await GeometriesModule.create(map, {
    label: { text: ['get', 'name'], size: 18, color: '#FFFFFF', haloColor: '#000000' },
    lineLabel: { minZoom: 10, size: 13, offset: [0, 1], symbolSpacing: 350 },
});

Unset label fields keep colours that adapt to the map style: dark text with a white halo on light styles, the reverse on dark ones.

Fill styles

The SDK supports three fill styles for polygon display:

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

Setting the fill style at config level

The simplest way to apply a fill style is via the fillStyle option in GeometriesModuleConfig:

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

// Highlight "rest of the world" outside a country
const module = await GeometriesModule.create(map, {
    fillStyle: 'inverted',
    fill: { color: 'black', opacity: 0.5 },
});
await module.show(countryGeometry);

Individual features can override the config-level fill style by setting fillStyle in their own properties.

Using fillStyledGeometryConfig for mixed fill styles

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

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

const module = await GeometriesModule.create(map, fillStyledGeometryConfig('blues'));

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

Color palettes

Both fillStyledGeometryConfig 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 { fillStyledGeometryConfig } from '@tomtom-org/maps-sdk/map';

// Use the 'retro' palette with the filled fill style (default)
const config = fillStyledGeometryConfig('retro');

// Palette names are typed as ColorPaletteOptions

For reachable ranges specifically, use reachableRangeGeometryConfig which builds on fillStyledGeometryConfig and additionally wires up label generation and the inverted fill style's 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.create(map, {
    fill: { color: '#E74C3C', opacity: 0.2 },
    line: { color: '#C0392B', width: 3 }
});

const cityBounds = await GeometriesModule.create(map, {
    fill: { color: '#3498DB', opacity: 0.3 },
    line: { color: '#2980B9', width: 2 }
});

// Each instance manages its own geometries independently
await countryBorders.show(countryData);
await 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