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:

• Displaying polygon geometries from TomTom services and custom data
• Visualizing administrative boundaries such as countries, states, and cities
• Rendering custom geographic shapes with configurable styling options
• Managing geometry layers with visibility controls and interaction handling
• Integrating geometry data from search results and external sources

Core concepts

Geometry data types

The module supports various types of geographic geometries:

Supported Geometry Types:

• Polygons: Closed shapes representing areas like administrative boundaries
• MultiPolygons: Complex shapes with multiple disconnected areas
• Administrative boundaries: Country, state, city, and district boundaries
• Custom shapes: User-defined geographic areas and regions

Data sources

Geometries can come from multiple sources:

• TomTom Geometry Data Service: Official administrative boundaries and places
• Search results: Geographic data from place searches
• Custom GeoJSON: User-provided geometric data
• External APIs: Third-party geographic data 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:

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 } (or a named palette instead of one colour) 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);
}

Restyling shown geometries

A config change reaches the geometries already on the map — their colours, fill style, labels and transformFeaturesForDisplay — without calling show() again. applyConfig replaces the whole config, so whatever it leaves out returns to the default; updateConfig changes only what it is given, and resetConfig returns to the defaults.

await geometryModule.show(cityBoundaries);

geometryModule.updateConfig({ fill: { palette: 'warm' }, fillStyle: 'outline' });
geometryModule.updateConfig({ label: { text: ['get', 'name'] } }); // keeps the palette and fill style
geometryModule.resetConfig(); // default colours, fill style and labels

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 record form { all?, fill?, line? }: a part takes its own entry, else all, else its default place just below the geometry titles. 'top' keeps the titles above everything else. moveBeforeLayer takes the same shape, and leaves a part it names no target for where it is.

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 styles it; lineLabel repeats it along the border, and is drawn only when set ({} for the defaults). Both take a text — a string or a MapLibre expression, the feature's title when unset — and the same styling fields as every module's labels: size, color, haloColor, haloWidth, opacity and font. lineLabel adds minZoom, symbolSpacing and offset:

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

// Later: restyle the center labels of the shown geometries
module.applyLabelConfig({ size: 20 });

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:

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?, beforeLayerConfig? }). 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({ palette: '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

fill.palette gives each feature the next colour of a named palette, so neighbouring polygons stay apart without assigning a colour to each. On dark map styles the palette's colours are adapted to stay legible.

Available palettes: warm, browns, cold, fadedBlues, blues, greens, fadedGreenToBlue, blueToRed, greenToYellow, pastel, retro, contrastRetro, fadedRainbow, pastelRainbow — colorPaletteIDs lists them, typed as ColorPaletteOptions.

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

const regions = await GeometriesModule.create(map, { fill: { palette: 'pastelRainbow', opacity: 0.3 } });

// fillStyledGeometryConfig and reachableRangeGeometryConfig take it as their `palette` option
const zones = await GeometriesModule.create(map, fillStyledGeometryConfig({ palette: 'retro' }));

fill.color takes a colour or an expression, fill.palette a palette name; where each sits in the order is the precedence table above.

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.

Every setting as data

geometriesKnobCatalogue lists every plain-valued display setting of the module with its kind, its range or options and, where one value holds everywhere, its default. Each id is the setting's path in the config, so a UI can build its controls from it, with no map loaded:

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

const borderKnobs = geometriesKnobCatalogue.filter(({ id }) => id.startsWith('line.'));
// [{ id: 'line.color', kind: 'color', description: '…' }, …,
//  { id: 'line.width', kind: 'number', description: '…', range: { min: 0, max: 20, step: 0.5, bounds: 'hard-min' } }]

• Opacities and widths have no default entry where the fill style decides it, and colours none where the accent or the map style does.
• Setting any lineLabel knob draws the border labels.
• A font knob's options are mapFonts; its order matters, since the first font the map has wins.
• lineLabel.offset is in ems, x along the line and y across it, [0, 1] unless set.
• geometriesKnobIds lists the ids in catalogue order, GeometriesKnobId is their union, and GeometriesKnobValueOf<ID> the plain value one takes.
• Not in it: beforeLayerConfig, the border line's full MapLibre layer, the labels' text, and transformFeaturesForDisplay, which take structured, MapLibre or function values; and events.
• Its entries share their shape, KnobEntry, with every module's catalogue.

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

• Geometry Data Service - Fetch detailed boundary and shape data for administrative areas and places
• Search Services - Find places and administrative areas that have associated geometry data

Related examples

• Basic Geometry - Simple geometry display and styling examples
• Multiple Geometries - Working with multiple geometry layers and data sets
• Multiple Geometry Modules - Advanced geometry module management and organization
• Geometry Config Playground - Fill and border colours, layer-stack positions and visibility
• Places in Geometry - Combining geometry boundaries with place markers
• Geometry Search Playground - Interactive geometry-based search and discovery

Related map modules

• Places Module - Display places and POIs within or related to geometric boundaries
• Routing Module - Show routes that intersect or travel through geometric areas
• User Interaction Events - Handle user interactions with geometric shapes and boundaries