Add vector tiles to a React app: production guide

What you need before writing React code

First identify what your tile provider actually publishes. A vector source may be exposed through a TileJSON URL, through one or more URL templates such as https://tiles.example.com/{z}/{x}/{y}.pbf, or through a complete style document that already declares sources and layers. MapLibre supports vector sources using MapLibre Tile or Mapbox Vector Tile formats. A TileJSON endpoint can carry metadata such as bounds, minimum and maximum zoom, and tile URL templates. (maplibre.org)

You also need the exact source-layer name inside the tile. A tileset can contain several thematic layers—such as roads, waterways, landuse, or buildings—and the source ID used in your application is not necessarily the same as the internal source-layer name. Obtain this value from the provider's documentation or inspect the tileset with a compatible vector-tile inspection tool before styling it.

• •A React application created with a supported Node.js LTS release.
• •The @vis.gl/react-maplibre and maplibre-gl packages.
• •A valid MapLibre style URL or a style object.
• •A vector-tile endpoint or TileJSON URL.
• •The source-layer name for each layer you intend to render.
• •A documented attribution string and any required access token or request headers.

Step 1: install the map and React bindings

The current react-maplibre getting-started documentation installs the React bindings together with MapLibre GL JS. It also requires the MapLibre stylesheet because controls, markers, popups, and other map UI elements depend on it. (visgl.github.io)

• •npm install @vis.gl/react-maplibre maplibre-gl
• •If the project uses TypeScript, keep the package versions aligned and run the project's normal type-check command after installation.
• •Do not install a Mapbox GL package unless your application intentionally targets Mapbox GL JS; the MapLibre React path uses MapLibre GL JS as its base library. (visgl.github.io)

Step 2: render a map with a style

Start with a known-good style before adding your own source. A style is a JSON document that defines the map's sources, layers, drawing order, and visual properties. The MapLibre Style Specification treats sources and layers as separate objects: a source identifies data, while a layer gives that data a visual representation. (maplibre.org)

• •import {Map} from '@vis.gl/react-maplibre';
• •import 'maplibre-gl/dist/maplibre-gl.css';
• •export default function App() {
• • return (
• • <Map
• • initialViewState={{
• • longitude: -122.4,
• • latitude: 37.8,
• • zoom: 10
• • }}
• • mapStyle="https://example.com/styles/base.json"
• • style={{width: '100%', height: '480px'}}
• • onError={(event) => console.error('Map error', event.error)}
• • />
• • );
• •}
• •A map container must have a usable width and height. A frequent integration failure is a correctly initialized map inside a parent whose height collapses to zero. Treat the map's dimensions as part of the component contract, not as an afterthought.

Step 3: add the vector source and a style layer

There are two normal ways to add the tiles. If the provider supplies TileJSON, use the url property. If it supplies a tile template, use the tiles array and include any documented minzoom, maxzoom, bounds, scheme, and attribution values. MapLibre's vector-source specification supports both forms. (maplibre.org)

• •import {Map, Source, Layer} from '@vis.gl/react-maplibre';
• •import type {FillLayer, LineLayer} from '@vis.gl/react-maplibre';
• •const roadsLayer: LineLayer = {
• • id: 'roads-line',
• • type: 'line',
• • source: 'local-tiles',
• • 'source-layer': 'roads',
• • paint: {
• • 'line-color': '#2563eb',
• • 'line-width': ['interpolate', ['linear'], ['zoom'], 8, 0.5, 14, 3]
• • }
• •};
• •export default function MapView() {
• • return (
• • <Map
• • initialViewState={{longitude: -122.4, latitude: 37.8, zoom: 10}}
• • mapStyle="https://example.com/styles/base.json"
• • style={{width: '100%', height: '600px'}}
• • >
• • <Source
• • id="local-tiles"
• • type="vector"
• • url="https://tiles.example.com/roads/tiles.json"
• • />
• • <Layer {...roadsLayer} />
• • </Map>
• • );
• •}
• •The key fields are source: 'local-tiles', which references the source ID declared in React, and source-layer: 'roads', which identifies the internal layer inside each vector tile. For a polygon dataset, use a fill layer; for linear features such as roads or streams, use a line layer; and for point-like features, use a circle or symbol layer. The layer type and paint properties should match the geometry and intended map scale. (maplibre.org)

Step 4: make the component production-aware

Keep stable source and layer objects outside the component or memoize them when they are expensive to recreate. The React bindings perform style diffing when layer props change, and their documentation notes that avoiding newly created constant objects and arrays can help performance. (visgl.github.io)

Use React state for application-level concerns such as the selected feature, active category, current filters, and whether a detail panel is open. Use the map ref or map hooks for map-specific operations such as fitting to bounds or flying to a selected location. The wrapper provides a MapRef and a useMap hook for these cases. (visgl.github.io)

• •Keep a stable layer definition rather than constructing a large object on every render.
• •Use filters in the style layer for visual selection when the complete dataset remains useful in the map.
• •Use a separate API query for authoritative feature details if the tile properties are intentionally generalized or abbreviated.
• •Handle onError and log the failing URL, source ID, and application route in your observability system.
• •Use onIdle or source-data events for diagnostics, not as a substitute for server-side data validation. (visgl.github.io)

Step 5: validate the delivery path before launch

Open browser developer tools and inspect the network requests while panning and zooming. Confirm that the application requests the expected z/x/y tiles, receives a successful status, and receives a content type and payload that the renderer can decode. A successful style request does not prove that the vector source is valid.

Test at several zoom levels, including below the source's minimum zoom, above its maximum zoom, and near the edges of its published bounds. MapLibre can reuse data from the maximum available zoom when displaying at higher zoom levels, but the visual result depends on how the tileset was generated and generalized. (maplibre.org)

• •Verify HTTPS and CORS for style, tile, glyph, sprite, and icon requests.
• •Verify required attribution is visible wherever the map is shown.
• •Check that the tile server returns cache headers appropriate for the update frequency of the data.
• •Test slow networks and interrupted requests; a map should fail visibly and recover gracefully.
• •Test touch, keyboard, resize, and high-density displays if the map is customer-facing.