Custom GeoJSON Module

The CustomGeoJSONModule lets you render arbitrary GeoJSON data on the map while keeping the lifecycle conveniences of the TomTom SDK: style-change restoration, configuration events, and per-source user interaction events (click, hover, long-hover, contextmenu). Unlike opinionated modules such as PlacesModule or GeometriesModule, this module makes no assumptions about how your data is rendered — you supply raw MapLibre layer specs (circle, heatmap, fill, line, symbol, …) and the module wires them to one or more managed GeoJSON sources.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { CustomGeoJSONModule, type StandardStyleID, standardStyleIDs, TomTomMap } from '@tomtom-org/maps-sdk/map';
import type { FeatureCollection, Point } from 'geojson';
import './style.css';
import { API_KEY } from './config';
import { buildMarkersLayers, heatmapLayers } from './layers';
import { initTogglePanel } from './togglePanel';

TomTomConfig.instance.put({ apiKey: API_KEY });

const map = new TomTomMap({
    mapLibre: {
        container: 'sdk-map',
        center: [-1.7, 53.75],
        zoom: 9.5,
    },
});

const DATA_URL = 'https://dataworks.calderdale.gov.uk/download/2kyp8/hcj/listed%20buildings%20west%20yorkshire.json';
const MARKER_ICON_ID = 'custom-marker';

type ListedBuilding = { Name?: string; Grade?: string };
type Sources = {
    heatmap: FeatureCollection<Point, ListedBuilding>;
    markers: FeatureCollection<Point, ListedBuilding>;
};

const createMarkerIcon = (size: number): ImageData => {
    const canvas = document.createElement('canvas');
    canvas.width = size;
    canvas.height = size;
    const context = canvas.getContext('2d') as CanvasRenderingContext2D;
    const center = size / 2;
    context.beginPath();
    context.arc(center, center, center - 1.5, 0, Math.PI * 2);
    context.fillStyle = '#0a3653';
    context.fill();
    context.lineWidth = 1.5;
    context.strokeStyle = '#ffffff';
    context.stroke();
    return context.getImageData(0, 0, size, size);
};

const initSelectionPanel = (customGeoJSON: CustomGeoJSONModule<Sources>) => {
    const selection = document.querySelector('#sdk-example-selection') as HTMLDivElement;

    customGeoJSON.events.markers.on('hover', (feature) => {
        const { Name } = (feature.properties ?? {}) as ListedBuilding;
        selection.innerHTML = `<strong>Hovering</strong>${Name ?? '(no name)'}`;
    });

    customGeoJSON.events.markers.on('click', (feature, lngLat) => {
        const { Name, Grade } = (feature.properties ?? {}) as ListedBuilding;
        selection.innerHTML =
            `<strong>${Name ?? '(no name)'}</strong>` +
            `${Grade ? `Grade ${Grade} · ` : ''}${lngLat.lng.toFixed(4)}, ${lngLat.lat.toFixed(4)}`;
    });
};

const initStyleSelector = () => {
    const selector = document.querySelector('#sdk-example-mapStyles') as HTMLSelectElement;
    standardStyleIDs.forEach((id) => selector.add(new Option(id)));
    selector.addEventListener('change', (event) =>
        map.setStyle((event.target as HTMLOptionElement).value as StandardStyleID),
    );
};

(async () => {
    const customGeoJSON = await CustomGeoJSONModule.get<Sources>(map, {
        sources: {
            heatmap: { layers: heatmapLayers },
            markers: { layers: buildMarkersLayers(MARKER_ICON_ID) },
        },
        images: { [MARKER_ICON_ID]: { image: createMarkerIcon(32), options: { pixelRatio: 2 } } },
    });

    await customGeoJSON.show(await (await fetch(DATA_URL)).json());

    initSelectionPanel(customGeoJSON);
    initStyleSelector();
    initTogglePanel();
})();

When to use this module

Reach for CustomGeoJSONModule when:

• You have your own GeoJSON data (BYOD) and the existing modules (PlacesModule, GeometriesModule, …) don’t fit the visualization you want.
• You need multiple visualizations of the same or related data — for example, a heatmap aggregation at low zoom and a symbol layer with labels at high zoom.
• You want the SDK to survive setStyle calls automatically — sources, layers and shown data are restored after every style swap, without you wiring up your own StyleChangeHandler.
• You want SDK-grade user events (click, hover, long-hover, contextmenu) and module lifecycle events (config-change, shown-features) on top of customer-owned layers.

If you only need to drop a single source/layer onto the map and don’t care about restoration or events, map.mapLibreMap.addSource(...) + map.mapLibreMap.addLayer(...) is simpler. See the MapLibre direct access guide .

Core concepts

Sources and layers

A CustomGeoJSONModule instance manages one or more named sources. Each source corresponds to a single MapLibre GeoJSON source and the layers that render it. Source names are caller-defined and used to address data via show(name, …), clear(name), and events.{name}.

1
import { CustomGeoJSONModule } from '@tomtom-org/maps-sdk/map';
2

3
const module = await CustomGeoJSONModule.get(map, {
4
    sources: {
5
        points: {
6
            layers: [
7
                { type: 'circle', paint: { 'circle-radius': 4, 'circle-color': '#0a3653' } },
8
            ],
9
        },
10
    },
11
});
12

13
await module.show(myFeatureCollection, 'points');

Each layer is a MapLibre LayerSpecification without the source field — the module assigns the source for you. Both the source ID and each layer ID are optional. When omitted they are auto-generated as:

• Source: custom-geojson-${moduleIndex}-${sourceName}
• Layer: ${sourceID}-layer-${layerIndex}

Provide explicit IDs when you want to refer to them from outside the module, or when the layer set may change at runtime and you need a stable identity that is independent of array order.

Generic types for source payloads

When you have a typed source schema, declare it as a generic on .get to get type-safe show, clear, getShown, and per-source events:

1
import type { FeatureCollection, Point, Polygon } from 'geojson';
2

3
type Sources = {
4
    heatmap: FeatureCollection<Point>;
5
    buildings: FeatureCollection<Polygon, { name: string }>;
6
};
7

8
const module = await CustomGeoJSONModule.get<Sources>(map, {
9
    sources: {
10
        heatmap: { layers: [{ type: 'heatmap', paint: { 'heatmap-radius': 12 } }] },
11
        buildings: { layers: [{ type: 'fill', paint: { 'fill-color': '#5a5' } }] },
12
    },
13
});
14

15
await module.show(heatmapData, 'heatmap');     // typed as FeatureCollection<Point>
16
await module.show(buildingData, 'buildings');  // typed as FeatureCollection<Polygon, { name: string }>

Without the generic, every source defaults to FeatureCollection.

Feature IDs

The module normalizes feature IDs at show() time. For every feature in the supplied collection:

• If both feature.id and feature.properties.id are present and equal, the feature is passed through untouched.
• If either is missing, the module fills the gap so that both end up with the same value (your explicit id if you supplied one on either field, otherwise the feature’s index in the array).

This is needed because feature event lookup depends on feature.id. MapLibre disables promoteId when a source is clustered, so without normalization clustered points share feature.id === undefined and every click resolves to the first one. The normalization keeps feature.id populated in both cluster and non-cluster mode, and keeps properties.id in sync so the non-cluster promoteId: 'id' path still maps correctly.

If you want to use your own IDs, just set feature.id (or feature.properties.id) on each feature — the module preserves them.

Showing and clearing data

1
// Replace the data on a single source
2
await module.show(newFeatureCollection, 'points');
3

4
// Read what's currently displayed (per source)
5
const { points } = module.getShown();
6

7
// Empty a single source
8
await module.clear('points');
9

10
// Empty every source
11
await module.clear();

Layer visibility follows the data automatically: a source’s layers are hidden when its feature collection is empty and revealed when it isn’t. Call setVisible(false) to force every layer across every source off, regardless of data state.

Multiple layers per source

A source can have any number of layers. This is how you combine, for example, a fill polygon with an outline, or a circle “halo” beneath a labeled icon. Order in the array reflects MapLibre draw order (later layers render on top).

1
const module = await CustomGeoJSONModule.get(map, {
2
    sources: {
3
        markers: {
4
            layers: [
5
                { type: 'circle', paint: { 'circle-radius': 6, 'circle-color': '#0a3653' } },
6
                {
7
                    type: 'symbol',
8
                    layout: {
9
                        'text-field': ['get', 'name'],
10
                        'text-offset': [0, 1.2],
11
                        'text-anchor': 'top',
12
                        'text-optional': true,
13
                    },
14
                    paint: { 'text-color': '#0a3653', 'text-halo-color': '#fff', 'text-halo-width': 1.5 },
15
                },
16
            ],
17
        },
18
    },
19
});

Symbol layers that use icon-image need the image to exist on the map before the layer renders any data. Use config.images to let CustomGeoJSONModule manage registration and style-change restoration for you — see Custom images below.

Custom images

When a symbol layer references an icon via icon-image: 'my-icon', the corresponding image has to be registered on the map (map.mapLibreMap.addImage) before the layer renders any feature. MapLibre also clears all custom images on every setStyle call, so a naive addImage registration only lasts until the next style swap.

CustomGeoJSONModule.config.images solves both problems. Images declared there are registered during module setup — before any source or layer is created — and re-registered after every style change as part of the same restoration pass that re-adds your sources and layers.

1
const module = await CustomGeoJSONModule.get(map, {
2
    sources: {
3
        markers: {
4
            layers: [
5
                {
6
                    type: 'symbol',
7
                    layout: { 'icon-image': 'my-marker', 'text-field': ['get', 'name'] },
8
                },
9
            ],
10
        },
11
    },
12
    images: {
13
        'my-marker': { image: myImageBitmap, options: { pixelRatio: 2 } },
14
    },
15
});

image accepts any payload that MapLibre’s addImage accepts (HTMLImageElement, ImageBitmap, ImageData, StyleImageInterface, or the { width, height, data } shape). Asynchronous sources — URLs and raw SVG strings — are not handled by the module; pre-load them and pass a loaded HTMLImageElement (or convert to ImageBitmap / ImageData). options is the Partial<StyleImageMetadata> argument forwarded verbatim (pixelRatio, sdf, stretchX, stretchY, content).

Existing images on the map are not overwritten — the module skips IDs for which map.hasImage(id) already returns true. This keeps multiple modules registering the same icon safe.

Clustering

Forward MapLibre’s cluster options verbatim on a per-source basis. Cluster features themselves are synthetic — they don’t appear in the source’s shown-features list, so the first argument to your click handler is undefined for cluster clicks. Fall back to the third argument, which always contains the rendered MapLibre feature with cluster: true, cluster_id, and point_count:

1
module.events.incidents.on('click', (feature, _lngLat, features) => {
2
    const properties = feature?.properties ?? features[0]?.properties ?? {};
3
    if (properties.cluster) {
4
        showCluster(properties.point_count);
5
    } else {
6
        showIncident(properties);
7
    }
8
});

Below is a typical cluster-aware source config:

1
const module = await CustomGeoJSONModule.get(map, {
2
    sources: {
3
        incidents: {
4
            cluster: { cluster: true, clusterRadius: 50, clusterMaxZoom: 14 },
5
            layers: [
6
                { type: 'circle', filter: ['has', 'point_count'],   paint: { 'circle-radius': 18 } },
7
                { type: 'symbol', filter: ['!', ['has', 'point_count']], layout: { 'icon-image': 'marker' } },
8
            ],
9
        },
10
    },
11
});

Cluster options are applied at source creation time and cannot be changed via applyConfig. To change clustering, recreate the module.

Style-change restoration

CustomGeoJSONModule extends the same AbstractMapModule base as the rest of the SDK’s GeoJSON modules. When map.setStyle(...) is called:

1. Images declared via config.images are re-registered on the map first.
2. The module’s sources and layers are re-added to the new style with the same IDs.
3. The most recently shown data on each source is re-applied via show.
4. Per-source config-change and shown-features handlers continue to fire normally.

You don’t need to register a StyleChangeHandler yourself for any of the above. Declare custom icons via config.images so the module also restores them — see Custom images .

Events

Each named source exposes its own CombinedEvents surface via module.events.{name}. Both user interaction events and module lifecycle events are available from the same handle:

1
const unsubscribe = module.events.points.on('click', (feature, lngLat, features) => {
2
    console.log('Clicked:', feature.properties);
3
    console.log('At:', lngLat);
4
});
5

6
module.events.points.on('hover', (feature) => { /* ... */ });
7
module.events.points.on('shown-features', (data) => {
8
    console.log(`Now showing ${data.features.length} points`);
9
});
10

11
// config-change handlers fire from any source's events — the handler list is module-wide
12
module.events.points.on('config-change', (config) => { /* ... */ });
13

14
unsubscribe();           // remove a specific handler
15
module.events.points.off('click');  // remove all click handlers on the points source

Registering through module.events rather than map.mapLibreMap.on(...) is what lets the SDK coordinate interactions when this module’s layers sit alongside other modules’ (Places, Routing, Geometries, …). The shared EventsProxy arbitrates overlapping layers, manages a single cursor state, and applies consistent hover / long-hover delays — so a click on a feature in your custom source doesn’t double-fire with a Places marker underneath, and the cursor doesn’t flicker between modules.

For the full event API (precision modes, hover delays, layer-order semantics), see User Events and Module Events .

Updating layers at runtime

Layer specs live inside config.sources rather than being a constructor argument, which means applyConfig can swap them at runtime. The module diffs the new layer set against the previous one and:

• Updates layers whose ID is present in both sets (paint, layout, zoom range, filter).
• Adds layers whose ID is new.
• Removes layers whose ID disappeared.

1
module.applyConfig({
2
    sources: {
3
        points: {
4
            layers: [
5
                { id: 'points-dot',   type: 'circle', paint: { 'circle-radius': 6, 'circle-color': '#c33' } },
6
                { id: 'points-label', type: 'symbol', layout: { 'text-field': ['get', 'name'] } },
7
            ],
8
        },
9
    },
10
});

Provide explicit ids on layers when you intend to mutate them this way — auto-generated IDs are position-based and shift if you reorder the array. Source-level changes (adding new source names, removing existing ones, or changing cluster options) are not supported by applyConfig; recreate the module instead.

Reading the underlying source and layer IDs

Use sourceAndLayerIDs to access the resolved MapLibre IDs for each source. This is useful when you need to call MapLibre APIs directly — for example, queryRenderedFeatures or setPaintProperty:

1
const ids = module.sourceAndLayerIDs;
2
// {
3
//   points: { sourceID: 'custom-geojson-0-points', layerIDs: ['custom-geojson-0-points-layer-0'] }
4
// }
5

6
const rendered = map.mapLibreMap.queryRenderedFeatures(undefined, {
7
    layers: ids.points.layerIDs,
8
});

Multiple module instances

You can create any number of CustomGeoJSONModule instances on the same map. Each gets a distinct instanceIndex, so auto-generated source and layer IDs never collide. Use multiple instances when you want to manage different data sets with independent lifecycles, configurations, or visibility states.

Related guides and examples

Related examples

• Bring Your Own Data: GeoJSON Heatmap with Custom Module — Heatmap + symbol layers with click/hover events, custom icons, and style switching
• Bring Your Own Data: Clusters and Polygons — 20k clustered points + random polygons, both clickable, with mock data generation
• Bring Your Own Data: Yorkshire Heatmap — A simpler BYOD heatmap using raw MapLibre + PlacesModule

Related map modules

• Places Module — Render TomTom Places (or compatible point data) with iconography and themes
• Geometries Module — Display polygon features with TomTom-style theming
• User Interaction Events — Full reference for click, hover, long-hover, contextmenu
• Module Events — config-change and shown-features lifecycle events
• Map Styles — setStyle, StyleChangeHandler, and style lifecycle