MapLibre GL JS gebruiken met de PDOK BRT-achtergrondkaart

MapLibre GL JS is een JavaScript-bibliotheek die vectortegels in de browser tekent met WebGL. Het project vat het zelf zo samen:

MapLibre GL JS is an open-source library for publishing maps on your websites or webview based apps. Fast displaying of maps is possible thanks to GPU-accelerated vector tile rendering.

Bron: README van maplibre-gl-js op GitHub, gelezen op 11 oktober 2026. Het project is begonnen als afsplitsing van mapbox-gl-js, na de overstap van Mapbox naar een niet-opensourcelicentie in december 2020.

Deze pagina gaat over het werken met MapLibre zelf. Of MapLibre, OpenLayers of Leaflet bij uw project past, met versies, licenties en gemeten bundelgroottes, staat in de gids Kaartbibliotheek kiezen.

PDOK biedt de BRT-achtergrondkaart aan als vectortegels volgens OGC API Tiles, in drie tegelschema's. De API beschrijft de dataset zo:

De BRT Achtergrondkaart is afgeleid uit TOP10NL uit de Basisregistratie Topografie (BRT).

Bron: landingspagina van de BRT Achtergrondkaart OGC API, gelezen op 11 oktober 2026.

De RD-variant bestaat voor toepassingen die RD New als kaartprojectie gebruiken, zoals OpenLayers. MapLibre rekent standaard in Web Mercator, dus u kiest de WebMercatorQuad-variant. Het verschil tussen vectortegels en de rastertegels van een WMTS staat op WMS en WMTS, en de afspraken voor intensief gebruik op PDOK fair use en caching.

U geeft de stijl-URL van PDOK door als style en laat MapLibre de bronnen, de lettertypen en de lagen ophalen. U hoeft zelf geen tegel-URL op te bouwen. Installeer maplibre-gl en zet in de pagina een element met id map en een hoogte.

import { Map, NavigationControl, setWorkerUrl } from 'maplibre-gl';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?url';
import 'maplibre-gl/dist/maplibre-gl.css';

// Sinds v6 is de worker een apart bestand; een bundler moet de URL ervan kennen.
setWorkerUrl(workerUrl);

const STYLE =
  'https://api.pdok.nl/kadaster/brt-achtergrondkaart/ogc/v1/styles/standaard__webmercatorquad?f=mapbox';

const map = new Map({
  container: 'map',
  style: STYLE,
  center: [5.3872, 52.1552], // [lengtegraad, breedtegraad], WGS84
  zoom: 15,
  maxZoom: 17.9, // de PDOK-tegels gaan tot niveau 17
  attributionControl: { customAttribution: 'Kaartgegevens © Kadaster (CC BY 4.0)' },
});

map.addControl(new NavigationControl());

map.on('load', () => {
  // Een eigen stijlwijziging op een laag uit de PDOK-stijl
  map.setPaintProperty('Gebouw', 'fill-color', '#c9d3f0');

  // Eigen GeoJSON bovenop de achtergrondkaart (WGS84)
  map.addSource('punt', {
    type: 'geojson',
    data: {
      type: 'Feature',
      properties: { naam: 'Onze Lieve Vrouwetoren' },
      geometry: { type: 'Point', coordinates: [5.3872, 52.1552] },
    },
  });
  map.addLayer({
    id: 'punt',
    type: 'circle',
    source: 'punt',
    paint: { 'circle-radius': 8, 'circle-color': '#2f4fd8', 'circle-stroke-width': 2, 'circle-stroke-color': '#ffffff' },
  });
});

Test op 11 oktober 2026: dit script is met vite build gebouwd en via de voorbeeldserver van Vite geladen in headless Chromium, met een kaartvlak van 800 bij 600 pixels. Alle negen verzoeken aan PDOK (stijl, tegels, lettertypen) gaven status 200. Na het laden stond de vulkleur van de laag Gebouw op de nieuwe waarde, queryRenderedFeatures vond 473 gebouwobjecten in beeld en de eigen puntlaag was zichtbaar. Het aantal gebouwen hangt af van de grootte van het kaartvlak.

Met customAttribution zet u de bronvermelding op de kaart. De licentie CC BY 4.0 vraagt daarom.

U wijzigt lagen uit de geladen stijl met setPaintProperty of voegt eigen lagen toe. De stijl van PDOK bestaat uit 19 lagen van de typen fill, line, symbol en circle. De laagnamen bevatten soms spaties en hoofdletters, dus neem ze letterlijk over.

Wie een eigen thema wil, kopieert de stijl als JSON naar het eigen project en past de kleuren daar aan. Dan ligt de stijl onder uw beheer, maar volgt hij PDOK niet meer automatisch. De tegels blijven bij PDOK staan, en daarom is bronvermelding en verantwoord gebruik uw verantwoordelijkheid. Voor een viewer van een gemeente staat het ontwerp van zo'n kaart ook in GIS- en kaartoplossingen.

In de uitgebrachte versie 6.14.0 niet: de typedefinities van het npm-pakket noemen alleen mercator, globe en vertical-perspective, en geen manier om een eigen stelsel te registreren. Op de hoofdtak van de repository is op 11 oktober 2026, na het uitbrengen van 6.14.0, wel een experimentele functie samengevoegd. De changelog onder ## main zegt:

Add addProjection, removeProjection, a built-in identity projection and a {bbox} tile URL token for maps in a custom planar CRS with its own quad tile grid

Bron: CHANGELOG.md van maplibre-gl-js, sectie main, gelezen op 12 oktober 2026; de wijziging is pull request #8723. Drie kanttekeningen volgen uit dat pull request en het bijbehorende issue. De functies zijn gemarkeerd als @experimental. GeoJSON-bronnen volgen een geregistreerde projectie nog niet en worden op de verkeerde plek getekend; daarvoor staat issue #8736 open. En de functie zit in geen enkele release op npm: de laatste versie blijft 6.14.0.

Moet de kaart nu in RD, dan is OpenLayers met proj4 de beproefde route. Volg de releaseopmerkingen van MapLibre als u RD later wilt overwegen.

De eerste twee valkuilen kwamen bij het testen van dit voorbeeld echt voor. De andere volgen uit de stijl van PDOK en de conventies van de bibliotheek.

• Geen standaardexport meer. import maplibregl from 'maplibre-gl' gaf in versie 6.14.0 de fout dat er geen export default is. Gebruik benoemde imports zoals import { Map } from 'maplibre-gl'.
• Het workerbestand. Een bundler die het pakket herschrijft, vindt het apart geleverde maplibre-gl-worker.mjs niet meer. De kaart bleef dan leeg met de melding Worker failed to load. Geef de URL mee via setWorkerUrl, zoals in het voorbeeld.
• Rij voor kolom in de tegel-URL. PDOK gebruikt het pad {z}/{y}/{x}, dus eerst de rij en dan de kolom. Wie zelf een bron opbouwt met de gewoonte {z}/{x}/{y} haalt de verkeerde tegels op. Neem de URL daarom uit de stijl over.
• Lengte voor breedte. MapLibre verwacht [lengtegraad, breedtegraad]. Wie die omdraait, belandt in de Zuidpool of in zee.
• Zoomniveau. De bron in de stijl heeft tegels tot niveau 17. Verder inzoomen levert geen extra detail, dus begrens maxZoom iets daarboven.

Vergeet de CSS niet: zonder maplibre-gl.css staan knoppen en bronvermelding ongestijld op de pagina.

MapLibre past niet als de kaart in RD New moet staan, bijvoorbeeld omdat WMS-lagen of bestaande RD-coördinaten rechtstreeks moeten passen. In de uitgebrachte versies kan dat niet, zoals hierboven beschreven.

De bibliotheek tekent met WebGL. Een kaart die uit één canvas bestaat, is niet vanzelf toegankelijk voor schermlezers, wat voor overheden extra aandacht vraagt. Lees daarvoor toegankelijke kaarten. Voor een kleine kaart met enkele markeringen en geen eigen stijl is een volledige vectorbibliotheek ook meer dan nodig.

Wie een volledige viewer wil, met zoeken, lagenbeheer en beheer, moet het ontwerp van de hele oplossing bekijken. TechinFlow levert zelf GIS-viewers en heeft daardoor belang bij deze vergelijking. De pagina GIS-viewer voor gemeenten beschrijft die dienst, en GIS-viewer kiezen vergelijkt de opties met bronnen.