About MapLibre

The TomTom Maps SDK for JavaScript renders through MapLibre GL JS, the open-source map renderer, and exposes it as is. This guide covers what that gives you, what the SDK adds on top, and when to use MapLibre directly.

MapLibre underneath, fully exposed

MapLibre is a peer dependency: you install it next to the SDK. TomTomMap does not hide it. map.mapLibreMap is the MapLibre Map itself, and the mapLibre constructor option takes MapLibre's map options unchanged:

• Compatibility: MapLibre controls, markers, popups, community plugins and examples work on a TomTom map as they are, and so does code written for MapLibre.
• Customization: whatever the SDK does not offer, MapLibre's full API still can, so you never hit a dead end.

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { TomTomMap } from '@tomtom-org/maps-sdk/map';
import { NavigationControl } from 'maplibre-gl';

TomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });

const map = new TomTomMap({ mapLibre: { container: 'map', pitch: 45 /* any MapLibre option */ } });

map.mapLibreMap.addControl(new NavigationControl(), 'top-right');
map.mapLibreMap.on('moveend', () => console.log('Viewport:', map.mapLibreMap.getBounds()));

What the SDK adds over raw MapLibre

Anything MapLibre can draw, the SDK's own features draw with less code and fewer ways to break:

• They survive style switches. Module data, configuration, layer placement and styling knobs are re-applied after every setStyle. MapLibre drops the sources, layers and images you added yourself.
• They survive style upgrades. Knobs and module settings are semantic, such as labels.sizeFactor or a route's color, and the SDK re-verifies them against every TomTom style release. Raw layer ids and paint expressions belong to one style version and are not a contract. See How durable is this?
• Their user events are smarter. One pipeline serves every module: the top-most feature receives the event instead of every overlapping layer, the cursor has one state, hover and long-hover have timing built in, clicks have tolerance, and handlers receive your original typed data. See User interaction events.
• They follow the map's theme. Routes, places, geometries and reachable ranges take the map's accent colour, so one setMapColors call restyles them along with the base map.
• Their settings are data. Every module lists its settings in a knob catalogue, validates what it is given, and saves and replays its configuration as JSON.

When to use TomTom SDK vs direct MapLibre

Use the SDK feature wherever one covers what you need:

Your own data belongs in CustomGeoJSONModule too, even a single layer. It takes the same layer specs as MapLibre's addLayer, so you keep MapLibre's full styling and gain the restoration and events above.

Use map.mapLibreMap for what none of these covers:

• Controls, markers and popups.
• Camera moves (flyTo, fitBounds) and map lifecycle events (load, moveend, zoom).
• Tile overlays: vector, raster and other non-GeoJSON sources.
• Third-party MapLibre plugins.

Sources, layers and images you add through map.mapLibreMap are yours to restore after setStyle, and sit outside the SDK's event coordination.

Combining both

SDK modules and the MapLibre API share one map:

import { TomTomConfig } from '@tomtom-org/maps-sdk/core';
import { PlacesModule, TomTomMap } from '@tomtom-org/maps-sdk/map';
import { discoverPlaces } from '@tomtom-org/maps-sdk/services';
import { Marker, Popup } from 'maplibre-gl';

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

// SDK: places that survive style switches, with coordinated events
const restaurants = await discoverPlaces({ query: 'restaurants' });
const placesModule = await PlacesModule.create(map);
await placesModule.show(restaurants);
placesModule.events.on('click', (feature) => console.log('Place clicked:', feature.properties.title));

// MapLibre: a marker with a popup
new Marker({ color: '#ff0000' })
    .setLngLat([4.9, 52.3])
    .setPopup(new Popup().setText('Custom Location'))
    .addTo(map.mapLibreMap);

MapLibre CSS

The SDK applies the MapLibre CSS itself unless your page already has it, so you do not need to import anything.

The stylesheet ships with the SDK:

• It is served from wherever your app serves the SDK, never from a third party.
• A strict Content Security Policy (style-src 'self') does not block it.
• It sits in a cascade layer, so your own CSS overrides it whatever order the two load in.

The bundled copy matches the MapLibre version the SDK was built with. To use the CSS of the MapLibre version you installed instead, import it in your JavaScript/TypeScript files:

import 'maplibre-gl/dist/maplibre-gl.css';

Prefer this import, which your bundler serves alongside your app, to a <link> to a public CDN such as unpkg.com: a CDN link sends every end user's IP address to that third party.

Related resources

• MapLibre GL JS documentation
• Custom GeoJSON module
• User interaction events
• Styling module
• Map styles