Interactieve Kaarten aan Uw Website Toevoegen | JavaScript Tutorial (2026) | MapAtlas Blog

Elk logistiek dashboard, onroerendgoedlijst en voedingsbezorgapp heeft één ding gemeen: een kaart. Als uw website er nog geen heeft, laat u context op tafel liggen. Context die gebruikers helpt locatie, nabijheid en ruimtelijke relaties in één oogopslag te begrijpen.

Deze tutorial begeleidt u door het toevoegen van een volledig interactieve kaart aan elk JavaScript-project. U begint met een weergegeven kaart, voegt markeringen en popups toe, koppelt adreszoeken via de Geocoding API en eindigt met een productie-klaar React-component die perfect in Next.js past.

Dit bouwt u aan het einde:

Een live vectorkaart geverifieerd met uw API-sleutel
Klikbare markeringen met aangepaste popup-inhoud
Een geocodering-aangedreven adreszoekfunctie
Een herbruikbare React-component met juiste opschoning en Next.js SSR-verwerking
Een checklist met prestatie-optimalisaties voor productie

Vereisten

Zorg voordat u begint dat u het volgende hebt:

Een MapAtlas API-sleutel (gratis aanmelden, geen creditcard vereist). Deze enkele sleutel verifieert elke MapAtlas-service: tegels, geocodering en routering.
Een JavaScript-project. Plain HTML, React, Vue of Svelte werken allemaal.
Node.js 18+ als u via npm installeert.

Stap 1: Installeer de MapAtlas SDK

Trek de SDK in uw project met npm:

npm install @mapmetrics/mapmetrics-gl

Als u met een simpele HTML-pagina werkt, plaats dan de CDN-links in uw <head>:

<link rel="stylesheet" href="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css" />
<script src="https://unpkg.com/@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.js"></script>

Sla de CSS-import niet over. Zonder deze CSS worden kaartbesturingselementen en popups zonder stijl weergegeven. Functioneel, maar visueel kapot.

Stap 2: Maak een Kaartcontainer

De SDK vult elk element dat u erop wijst, dus u hebt een <div> nodig met een expliciete hoogte. Dit is de singuliere meest voorkomende installatiefout: als de container height: 0 heeft, initialiseert de kaart maar blijft onzichtbaar.

<div id="map" style="width: 100%; height: 500px;"></div>

Een vaste pixelwaarde of viewport-eenheid (100vh, 50vh) werken beide. Percentagehoogtes werken alleen als het bovenliggende element ook een gedefinieerde hoogte heeft.

Stap 3: Geef Uw Eerste Interactieve Kaart Weer

Drie regels configuratie zijn alles wat nodig is: een container, een style-URL met uw API-sleutel en een startpositie.

import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
  center: [4.9041, 52.3676],
  zoom: 12,
});

Open de pagina en u ziet een vectorkaart die u kunt slepen, schuiven en knijpen om te navigeren. Tegels worden op aanvraag van MapAtlas-servers geladen, dus er is geen zware vooruitbetaling.

Het Kiezen van een Kaartstijl

Vervang het padsegment in de style-URL om het uiterlijk volledig te veranderen:

Stijl	URL-pad	Het Beste Voor
Basic	`/styles/basic/style.json`	Generieke apps
Bright	`/styles/bright/style.json`	Gegevensvisualisatie-overlays
Dark	`/styles/dark/style.json`	Dashboards, donker thema, analyses

Snelle winst: Gebruik de donkere stijl voor beheerderspanelen en gereedschappen die in donkere omgevingen worden gebruikt. Het vermindert oogvermoeidheid en doet gegevenslagen zoals heatmaps en routelijnen visueel opvallen tegen de achtergrond.

Stap 4: Voeg Markeringen en Popups aan Uw Kaart Toe

Een kaart zonder markeringen is slechts een achtergrondafbeelding. Markeringen veranderen een statische weergave in iets waarmee gebruikers kunnen interageren.

const popup = new mapmetricsgl.Popup().setHTML(`
  <strong>Amsterdam Central</strong>
  <p>Stationsplein, 1012 AB Amsterdam</p>
`);

new mapmetricsgl.Marker({ color: '#97C70A' })
  .setLngLat([4.9001, 52.3791])
  .setPopup(popup)
  .addTo(map);

Klik op de markering en de popup opent. U kunt elke HTML erin plaatsen: adressen, miniaturen, CTA-knoppen, wat uw UI ook nodig heeft.

Meerdere Markeringen uit Gegevens Uitzetten

De meeste real-world apps hebben meer dan één markering nodig. Loop door een array en maak voor elke invoer een markering:

const locations = [
  { name: 'Amsterdam', coords: [4.9041, 52.3676] },
  { name: 'Rotterdam', coords: [4.4777, 51.9244] },
  { name: 'Utrecht',   coords: [5.1214, 52.0907] },
];

locations.forEach(({ name, coords }) => {
  const popup = new mapmetricsgl.Popup().setHTML(`<strong>${name}</strong>`);
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat(coords)
    .setPopup(popup)
    .addTo(map);
});

Prestatie-opmerking: Zodra u ruwweg 100 tot 200 markeringen overschrijdt, vertraagt de weergave merkbaar bij ingezoomde weergaven. Schakel GeoJSON-bronclusterering in (nativelijk ondersteund door de SDK) om nabijgelegen markeringen bij lage zoomsniveaus te groeperen. Raadpleeg de SDK-documentatie voor clusteringconfiguratie.

Stap 5: Voeg Adreszoeken toe met de Geocoding API

De Geocoding API verandert een tekstquery (een straatwegadres, stadsnaam of oriëntatiepunt) in coördinaten waarop u kunt pannen, markeren of die u in een routeringsaanvraag kunt invoeren.

async function searchAddress(query) {
  const url = new URL('https://api.mapatlas.eu/geocoding/v1/search');
  url.searchParams.set('text', query);
  url.searchParams.set('key', 'YOUR_API_KEY');
  const res  = await fetch(url);
  const data = await res.json();
  if (!data.features.length) return;
  const [lng, lat] = data.features[0].geometry.coordinates;
  const label      = data.features[0].properties.label;
  map.flyTo({ center: [lng, lat], zoom: 14 });
  new mapmetricsgl.Marker({ color: '#97C70A' })
    .setLngLat([lng, lat])
    .setPopup(new mapmetricsgl.Popup().setHTML(`<strong>${label}</strong>`))
    .addTo(map);
}
searchAddress('Rijksmuseum, Amsterdam');

Resultaten worden geretourneerd als GeoJSON-features, dus ze sluiten direct aan op elke GeoJSON-compatibele laag, gegevenstabel of downstreamAPI-aanroep.

Bouw in minder dan 30 regels een live zoekbalk: Koppel searchAddress aan de input-event van een tekstveld, debounce het met 300ms, en u hebt kaartzoeken in autocomplete-stijl zonder extra afhankelijkheden.

Interactieve Kaarten Integreren met React

Een Herbruikbare Kaartcomponent

Verpak de kaartinitialisatie in useEffect zodat deze wordt uitgevoerd na DOM-mount en retourneer een opschoningsfunctie om geheugenlekkages bij unmount te voorkomen:

import { useEffect, useRef } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

export function MapAtlasMap({ apiKey, center = [4.9041, 52.3676], zoom = 12 }) {
  const containerRef = useRef(null);
  useEffect(() => {
    const map = new mapmetricsgl.Map({
      container: containerRef.current,
      style: `https://tiles.mapatlas.eu/styles/basic/style.json?key=${apiKey}`,
      center, zoom,
    });
    return () => map.remove();
  }, [apiKey]);
  return <div ref={containerRef} style={{ width: '100%', height: '500px' }} />;
}

Gebruik het overal in uw componentenboom:

<MapAtlasMap apiKey={process.env.NEXT_PUBLIC_MAPATLAS_KEY} center={[4.9041, 52.3676]} zoom={13} />

Next.js Server-Side Rendering Verwerken

De kaart-SDK is afhankelijk van browser-API's (window, document) die niet bestaan tijdens SSR. Importeer de component dynamisch met SSR uitgeschakeld:

import dynamic from 'next/dynamic';
const MapAtlasMap = dynamic(
  () => import('./MapAtlasMap').then(m => m.MapAtlasMap),
  { ssr: false, loading: () => (<div style={{ height: 500, background: '#f0f1f3', borderRadius: 12 }} />) }
);

De loading-placeholder houdt uw lay-out stabiel terwijl de kaartbundel wordt gedownload, waardoor cumulatieve lay-outverschuiving (CLS) wordt voorkomen. Dit is belangrijk voor zowel gebruikerservaring als Core Web Vitals.

Productie Prestatie-Checklist

Voordat u gaat publiceren, voert u deze optimalisaties uit:

Lazy-load kaarten onder de vouw. Gebruik IntersectionObserver om de kaart alleen te initialiseren wanneer de container in de weergave schuift. Dit stelt ongeveer 200 KB JavaScript uit van het initiële pagina-laden.
Zet in op vectortegels. Vectortegels schalen netjes naar elke schermresolutie, laden sneller dan rasterafbeeldingen en kunnen volledig aan de clientzijde in stijl worden gewijzigd zonder extra serveraanvragen. MapAtlas levert standaard vectortegels.
Cluster grote markeringsets. Bij meer dan 100 tot 200 markeringen veroorzaakt niet-geclusterde weergave bij ingezoomde weergaven merkbare frame drops. Clustering lost dit volledig op.
Houd uw API-sleutel aan de serverzijde. Maak nooit sleutels vast in een openbare repository. Gebruik omgevingsvariabelen (NEXT_PUBLIC_MAPATLAS_KEY in Next.js) of proxy-aanvragen via uw backend voor gevoelige bewerkingen.
Stel maxBounds in voor regionale apps. Als uw gebruikers zich alleen zorgen maken over één geografie, beperkt u de viewport zodat tegels buiten dat gebied nooit worden aangevraagd. Minder netwerkoproepen, sneller laden.

Wat U Volgende Kunt Bouwen

U hebt een kaart die rendert, markeringen toont, adressen zoekt en met React integreert. Dit is waar u heen gaat:

Routing API: Vraag routebeschrijvingen van afslag tot afslag aan tussen twee coördinaten. Retourneert een routepolyline, totale afstand en geschatte reistijd.
Isochrone API: Genereer een veelhoek die elk punt omvat dat bereikbaar is binnen n minuten. Gebruikt voor bezorgzones, servicedekking kaarten en analyse van opvanggebieden.
Matrix API: Bereken reistijd en afstand tussen meerdere origins en bestemmingen in één aanvraag. Essentieel voor flottabezorging en logistieke optimalisatie.

Volledige SDK-referentie, stijldocumentatie en API-gidsen zijn beschikbaar op docs.mapatlas.xyz.

Veelgestelde Vragen

Kan ik gratis interactieve kaarten aan mijn website toevoegen?

Ja. MapAtlas biedt een gratis laag zonder creditcard vereist bij aanmelding. Het omvat vectortegelweergave, de Geocoding API en de Routing API. Dit is voldoende voor ontwikkeling en kleinschalige productiegebruik.

Hoe voeg ik een kaart in een React- of Next.js-app in?

Verpak de kaartinitialisatie in een useEffect-haak zodat deze wordt uitgevoerd na DOM-mount. Gebruik in Next.js dynamic() met ssr: false om server-side rendering fouten te voorkomen. Beide benaderingen worden met copy-paste voorbeelden in deze tutorial behandeld.

Wat zijn vectortegels en waarom moet ik ze gebruiken in plaats van raster?

Vectortegels beschrijven kaartfuncties (wegen, gebouwen, labels) als wiskundige geometrie in plaats van voorgerenderde pixelafbeeldingen. Ze schalen netjes naar elke resolutie, laden sneller en kunnen volledig aan de clientzijde worden herzien zonder extra serverrondes.

Hoeveel markeringen kan ik toevoegen voordat de prestaties afnemen?

Weergave verslechtert zich doorgaans voorbij 100 tot 200 markeringen bij lage zoomniveaus. De oplossing is clustering: de MapAtlas SDK ondersteunt GeoJSON-bronclusterering nativelijk, groeperen van nabijgelegen markeringen bij laag zoomen en uitvouwen wanneer de gebruiker inzoomt.

Heb ik GIS-ervaring nodig om MapAtlas te gebruiken?

Nee. De SDK is ontworpen voor webontwikkelaars, niet voor GIS-specialisten. U initialiseert een kaart met coördinaten en een zoomniveau, voegt markeringen toe met lengtegraad/breedtegraad-paren en roept de Geocoding API aan met gewone tekst. Geen ruimtelijke databases of GIS-gereedschappen vereist.

Interactieve Kaarten aan Uw Website Toevoegen | JavaScript Tutorial (2026)