Do I need react-map-gl or can I use maplibre-gl directly?

You can use maplibre-gl directly, but react-map-gl handles cleanup, viewport state, and re-renders for you. Most React teams ship faster with the wrapper.

Is maps.guru compatible with Next.js client components?

Yes. Mark the map component with `"use client"` and dynamic-import it with `ssr:false` so the WebGL context never runs during SSR.

How do I authenticate tile requests from React?

Pass the `?key=` query on the style URL. maplibre-gl forwards the same auth through to every tile, sprite, and glyph request automatically.

maps.guru

maps for react

React maps, the boring infra part
sorted.

Wrap maplibre-gl in the official react-map-gl adapter for declarative React components. Drop in <Map> + <Source> + <Layer> and stay purely React, with no imperative DOM ref handling.

Get a free API key React docs

install

pnpm add maplibre-gl react-map-gl

tsx

import 'maplibre-gl/dist/maplibre-gl.css';
import Map, { Source, Layer, NavigationControl } from 'react-map-gl/maplibre';

const MAP_STYLE = 'https://maps.guru/api/v1/styles/standard/light/style.json?key=YOUR_API_KEY';

export function CityMap() {
  return (
    <Map
      initialViewState={{ longitude: 77.209, latitude: 28.6139, zoom: 11 }}
      mapStyle={MAP_STYLE}
      style={{ width: '100%', height: 480 }}
    >
      <NavigationControl position="top-right" />
      <Source
        id="places"
        type="geojson"
        data="https://maps.guru/api/v1/datasets/your-dataset/geojson?key=YOUR_API_KEY"
      >
        <Layer
          id="places-fill"
          type="circle"
          paint={{
            'circle-radius': 6,
            'circle-color': '#e66200',
            'circle-stroke-width': 2,
            'circle-stroke-color': '#fcfaf6',
          }}
        />
      </Source>
    </Map>
  );
}

live · React preview

Why React teams ship on maps.guru

Free-tier generous enough for real production traffic. 50,000 tile requests/month , no credit card.

Use react-map-gl/maplibre for full TypeScript types and React 18+ concurrent rendering.
Compose maps declaratively with <Source> + <Layer> JSX instead of imperative map.addLayer() calls.
Subscribe to map events via onLoad / onViewportChange for in-component state and SSR-friendly rendering.

Frequently asked

Do I need react-map-gl or can I use maplibre-gl directly?
You can use maplibre-gl directly, but react-map-gl handles cleanup, viewport state, and re-renders for you. Most React teams ship faster with the wrapper.
Is maps.guru compatible with Next.js client components?
Yes. Mark the map component with `"use client"` and dynamic-import it with `ssr:false` so the WebGL context never runs during SSR.
How do I authenticate tile requests from React?
Pass the `?key=` query on the style URL. maplibre-gl forwards the same auth through to every tile, sprite, and glyph request automatically.

Mapping terms for React developers, defined

The vocabulary behind vector tiles, styles, and geocoding, in plain language.

What is Vector tile?: A vector tile is a compressed binary chunk of map geometry (roads, buildings, labels) that the browser styles and renders at runtime, instead of downloading a pre-drawn image. Vector tiles let one dataset power unlimited visual styles and stay sharp at every zoom level.
What is Basemap?: A basemap is the background map layer (roads, water, landuse, place labels) that your own data is drawn on top of. maps.guru serves basemaps as MapLibre-compatible vector tiles.
What is Map style?: A map style is a JSON document that tells a renderer which colours, fonts, widths, and zoom rules to apply to each layer of a vector tile. maps.guru styles follow the MapLibre Style Specification, so they work in any MapLibre or Mapbox GL JS compatible renderer.
What is Geocoding?: Geocoding is the process of converting a text address or place name into latitude and longitude coordinates. Reverse geocoding does the opposite: it converts coordinates into the nearest human-readable address.
What is PMTiles?: PMTiles is a single-file archive format for map tiles that supports HTTP range requests, so a tile server can read one tile out of a multi-gigabyte archive without unpacking it. maps.guru stores its tile archives as PMTiles on Cloudflare R2.
What is MapLibre GL JS?: MapLibre GL JS is an open-source WebGL map renderer, forked from Mapbox GL JS v1 after that project moved to a proprietary licence. It is the reference renderer for maps.guru styles and carries no per-render licence fee.
What is Tile request?: A tile request is one HTTP fetch of a single map tile. A typical desktop map view loads roughly 10 to 20 tiles, and panning or zooming loads more, which is why tile quotas are counted in tens of thousands rather than page views.
What is Static map?: A static map is a server-rendered PNG or JPEG image of a map at a fixed centre, zoom, and size. Static maps are used where an interactive map cannot run: email, PDF exports, Open Graph share cards, and AI chat replies.

Sources

MapLibre Style Specification — MapLibre
Mapbox Vector Tile specification — Mapbox
MapLibre GL JS documentation — MapLibre
OpenStreetMap tile usage policy — OpenStreetMap Foundation

Maps for other frameworks

tsx
Next.js
SSR-safe maps inside the App Router.
See snippet
vue
Vue
@geoql/v-maplibre: our own Vue 3 wrapper for MapLibre.
See snippet
html
JavaScript
Drop-in maplibre-gl via CDN with no build step.
See snippet

Ready to build with
beautiful basemaps?

Join developers worldwide who trust maps.guru for their mapping needs. Start free, no credit card required.

Free forever plan

5-minute setup

No credit card

React maps, the boring infra part sorted.

Why React teams ship on maps.guru

Frequently asked

Do I need react-map-gl or can I use maplibre-gl directly?

Is maps.guru compatible with Next.js client components?

How do I authenticate tile requests from React?

Mapping terms for React developers, defined

What is Vector tile?

What is Basemap?

What is Map style?

What is Geocoding?

What is PMTiles?

What is MapLibre GL JS?

What is Tile request?

What is Static map?

Sources

Maps for other frameworks

Ready to build withbeautiful basemaps?

React maps, the boring infra part
sorted.

Ready to build with
beautiful basemaps?