About MapLibre

This guide explains how the TomTom Maps SDK for JavaScript integrates with MapLibre GL JS and when to use each library directly.

MapLibre GL JS overview

MapLibre GL JS is an open-source TypeScript library for publishing interactive maps on websites. It provides powerful capabilities for displaying beautiful maps, adding data, and creating user interactions.

TomTom's MapLibre strategy

TomTom officially supports MapLibre as part of our commitment to open-source mapping technologies and OpenStreetMap data integration.

MapLibre GL JS is used as a peer dependency. This means developers must install MapLibre separately to use it alongside the TomTom Maps SDK.

To learn how you can leverage MapLibre, check its live examples.

The TomTom Maps SDK builds on MapLibre to provide:

TomTom-specific functionality: Seamless integration with TomTom services
Simplified APIs: Easier access to complex mapping features
Consistent styling: Pre-built TomTom map styles and themes
Service integration: Direct connection to TomTom's routing, search, and traffic services

Direct MapLibre access

Every TomTom map instance provides direct access to the underlying MapLibre map:

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

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

const tomtomMap = new TomTomMap({ mapLibre: { container: 'map' /* pass other maplibre config */ }});

const maplibreMap = tomtomMap.mapLibreMap;

// Add maplibre event listener
maplibreMap.on('click', (event) => {
    console.log('Map clicked at:', event.lngLat);
});

// Add MapLibre controls
maplibreMap.addControl(new mapLibre.NavigationControl(), 'top-right');

When to use TomTom SDK vs direct MapLibre

map.mapLibreMap is always an option. Prefer the SDK's own mechanisms first: they survive style switches, are re-verified against each TomTom style release, and share one event system.

To…	Use
Switch or load a style	`setStyle`
Restyle the TomTom map: sizes, colours, features	`StylingModule`
Show or hide base map, POI, traffic and terrain parts	`BaseMapModule`, `POIsModule`, `TrafficFlowModule`, `TrafficIncidentsModule`, `TerrainModule`
Show places, routes, geometries and reachable ranges	`PlacesModule`, `RoutingModule`, `GeometriesModule`, `ReachableRangesModule`, each styled through its own config
Draw your own GeoJSON data	`CustomGeoJSONModule`: your MapLibre layer specs, restored after style changes, with SDK click and hover events

Use MapLibre directly for what none of these covers, such as controls, markers, popups and low-level map events. Sources, layers and images you add that way are yours to restore after setStyle, and they sit outside the SDK's event coordination.

Hybrid development approach

The most effective approach combines both libraries:

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';

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

// Use TomTom services for business logic
const restaurants = await discoverPlaces({ query: 'restaurants' });
const placesModule = await PlacesModule.create(map);
await placesModule.show(restaurants);

// Use MapLibre for custom features
const customMarker = new Marker({ color: '#ff0000' });

customMarker.setLngLat([4.9, 52.3]).setPopup(new Popup().setText('Custom Location')).addTo(map.mapLibreMap);

// Combine event handling
placesModule.events.on('click', (feature) => {
    console.log('TomTom place clicked:', feature.properties.title);
});

map.mapLibreMap.on('click', (event) => {
    console.log('Map clicked at:', event.lngLat);
});

Benefits of this integration

For developers

Flexibility: Choose the right tool for each task
Future-proof: Direct access to MapLibre ensures compatibility
Learning curve: Familiar MapLibre APIs remain available
Community: Access to both TomTom and MapLibre communities

For applications

Performance: Leverage MapLibre's optimized rendering
Functionality: Access TomTom's comprehensive service ecosystem
Customization: Full control over map appearance and behavior
Scalability: Build from simple to complex mapping applications

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.