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';import 'maplibre-gl/dist/maplibre-gl.css';
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 listenermaplibreMap.on('click', (event) => { console.log('Map clicked at:', event.lngLat);});
// Add MapLibre controlsmaplibreMap.addControl(new mapLibre.NavigationControl(), 'top-right');When to Use TomTom SDK vs Direct MapLibre
Use TomTom SDK For:
TomTom Service Integration:
import { PlacesModule, TomTomMap } from '@tomtom-org/maps-sdk/map';import { search } from '@tomtom-org/maps-sdk/services';
const results = await search({ query: 'restaurants' });const placesModule = await PlacesModule.get(tomtomMap);placesModule.show(results);Use Direct MapLibre For:
Custom Map Layers:
// Custom data layersmaplibreMap.addSource('custom-data', { type: 'geojson', data: customGeoJSON});
maplibreMap.addLayer({ id: 'custom-layer', type: 'circle', source: 'custom-data', paint: { 'circle-radius': 8, 'circle-color': '#ff0000' }});
// Custom style modificationsmaplibreMap.setPaintProperty('building-layer', 'fill-color', '#00ff00');
// Detailed event controlmaplibreMap.on('sourcedata', (event) => { if (event.sourceId === 'my-source' && event.isSourceLoaded) { console.log('Source loaded'); }});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 { search } from '@tomtom-org/maps-sdk/services';import { Marker, Popup } from 'maplibre-gl';
// Initialize with TomTom SDKTomTomConfig.instance.put({ apiKey: 'YOUR_API_KEY' });const map = new TomTomMap({ mapLibre: { container: 'map' } });
// Use TomTom services for business logicconst restaurants = await search({ query: 'restaurants' });const placesModule = await PlacesModule.get(map);placesModule.show(restaurants);
// Use MapLibre for custom featuresconst customMarker = new Marker({ color: '#ff0000' });
customMarker.setLngLat([4.9, 52.3]).setPopup(new Popup().setText('Custom Location')).addTo(map.mapLibreMap);
// Combine event handlingplacesModule.events.on('click', (feature) => { console.log('TomTom place clicked:', feature.properties.name);});
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