Skip to content

chore: upgrade website and examples to MapLibre v6 #2602

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
chrisgervang merged 6 commits into from
Jul 29, 2026
Merged

chore: upgrade website and examples to MapLibre v6 #2602

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
30088af
chore: upgrade website and examples to MapLibre v6
chrisgervang Jul 29, 2026
edda788
fix: configure MapLibre v6 workers
chrisgervang Jul 29, 2026
5cb8df6
docs: clarify MapLibre v6 imports
chrisgervang Jul 29, 2026
e77de93
docs: format MapLibre version guidance
chrisgervang Jul 29, 2026
793c464
docs: document MapLibre v6 support
chrisgervang Jul 29, 2026
bdef0d5
docs: clean up MapLibre guidance formatting
chrisgervang Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion docs/api-reference/maplibre/geolocate-control.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ You may use it to call any imperative methods:
import * as React from 'react';
import {useRef, useEffect} from 'react';
import {Map, GeolocateControl} from 'react-map-gl/maplibre';
import type maplibregl from 'maplibre-gl';
import type * as maplibregl from 'maplibre-gl';

function App() {
const geoControlRef = useRef<maplibregl.GeolocateControl>();
Expand Down
5 changes: 2 additions & 3 deletions docs/api-reference/maplibre/map.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -444,7 +444,7 @@ By module import (and embedding in the final bundle):
```tsx
import * as React from 'react';
import {Map} from 'react-map-gl/maplibre';
import maplibregl from 'maplibre-gl';
import * as maplibregl from 'maplibre-gl';

function App() {
return <Map mapLib={maplibregl} />;
Expand Down Expand Up @@ -508,8 +508,7 @@ The number of web workers instantiated on a page with maplibre-gl maps.

#### `workerUrl`: string {#workerurl}

Provides an interface for loading maplibre-gl's WebWorker bundle from a self-hosted URL. This is useful if your site needs to operate in a strict CSP (Content Security Policy) environment wherein you are not allowed to load JavaScript code from a Blob URL, which is default behavior.

Provides an interface for loading maplibre-gl's WebWorker bundle from a self-hosted URL. MapLibre GL JS v6 applications that use a bundler must configure the worker before rendering a map. Follow MapLibre's [installation instructions](https://maplibre.org/maplibre-gl-js/docs/#installation) to generate the appropriate worker URL for your bundler.
Comment on lines 509 to +511

@chrisgervang chrisgervang Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if examples can use this instead of setWorkerUrl



## Methods
Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/maplibre/marker.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ You may use it to call any imperative methods:
import * as React from 'react';
import {useRef, useMemo, useCallback} from 'react';
import {Map, Marker} from 'react-map-gl/maplibre';
import maplibregl from 'maplibre-gl';
import * as maplibregl from 'maplibre-gl';

function App() {
const markerRef = useRef<maplibregl.Marker>();
Expand Down
2 changes: 1 addition & 1 deletion docs/api-reference/maplibre/popup.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -99,7 +99,7 @@ You may use it to call any imperative methods:
import * as React from 'react';
import {useRef, useEffect} from 'react';
import {Map, Popup} from 'react-map-gl/maplibre';
import maplibregl from 'maplibre-gl';
import * as maplibregl from 'maplibre-gl';

@chrisgervang chrisgervang Jul 29, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Type only import?


function App() {
const popupRef = useRef<maplibregl.Popup>();
Expand Down
15 changes: 15 additions & 0 deletions docs/get-started/get-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,21 @@ npm install react-map-gl mapbox-gl @types/mapbox-gl
npm install react-map-gl maplibre-gl
```

MapLibre GL JS imports depend on the version:

```tsx
// MapLibre v4/v5
import maplibregl from 'maplibre-gl';

// MapLibre v6
import * as maplibregl from 'maplibre-gl';
// or use named imports
```

MapLibre v6 applications that use a bundler must also configure the worker before rendering a map.

Follow MapLibre's [installation instructions](https://maplibre.org/maplibre-gl-js/docs/#installation) for your bundler. The MapLibre get-started example uses Vite's recommended `?worker&url` import.

</TabItem>
</Tabs>

Expand Down
4 changes: 3 additions & 1 deletion docs/whats-new.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,9 @@ Release date: Oct 2025

The core logic in the Mapbox GL JS wrapper has been rewritten to use [Proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) to intercept camera updates. We expect the new approach to improve camera synchronization between the native controller and React props when terrain and/or non-mercator projections are used. See more backgrounds in [#2514](https://github.com/visgl/react-map-gl/pull/2514).

The Maplibre wrapper is unaffected by this change.
The MapLibre wrapper is unaffected by this change.

The v8.1 release line supports MapLibre GL JS v4, v5 and v6. MapLibre v6 applications must use named or namespace imports and configure the worker when using a bundler. See the [Get Started guide](./get-started/get-started.md) for setup instructions and MapLibre's [v5 to v6 migration guide](https://maplibre.org/maplibre-gl-js/docs/guides/v5-to-v6-migration-guide/) for other changes in MapLibre v6.

## react-map-gl v8.0

Expand Down
5 changes: 5 additions & 0 deletions examples/get-started/maplibre/app.jsx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,15 @@
/* global document */
import * as React from 'react';
import {createRoot} from 'react-dom/client';
// eslint-disable-next-line import/namespace
import {setWorkerUrl} from 'maplibre-gl';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import Map, {Marker} from 'react-map-gl/maplibre';

import 'maplibre-gl/dist/maplibre-gl.css';

setWorkerUrl(workerUrl);

function Root() {
return (
<Map
Expand Down
2 changes: 1 addition & 1 deletion examples/get-started/maplibre/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
"build": "vite build"
},
"dependencies": {
"maplibre-gl": "^5.0.0",
"maplibre-gl": "^6.0.0",
Comment thread
cursor[bot] marked this conversation as resolved.
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0"
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/clusters/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -34,7 +33,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/clusters/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/controls/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -34,7 +33,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/controls/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/custom-cursor/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -45,7 +44,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/custom-cursor/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/custom-overlay/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -48,7 +47,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/custom-overlay/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/deckgl-overlay/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand All @@ -20,7 +19,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/deckgl-overlay/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/draggable-markers/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -35,7 +34,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/draggable-markers/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"build": "vite build"
},
"dependencies": {
"maplibre-gl": "^5.0.0",
"maplibre-gl": "^6.0.0",
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0"
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/draw-polygon/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -34,7 +33,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/draw-polygon/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/filter/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -40,7 +39,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/filter/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@
"build": "vite build"
},
"dependencies": {
"maplibre-gl": "^5.0.0",
"maplibre-gl": "^6.0.0",
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0"
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/geocoder/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -34,7 +33,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/geocoder/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
5 changes: 4 additions & 1 deletion examples/maplibre/geojson-animation/index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,6 @@
<head>
<meta charset='UTF-8' />
<title>react-maplibre Example</title>
<link href="https://unpkg.com/maplibre-gl@4.7.0/dist/maplibre-gl.css" rel="stylesheet">
<style>
body {
margin: 0;
Expand Down Expand Up @@ -34,7 +33,11 @@
<div id="map"></div>
</body>
<script type="module" type="text/javascript">
import {setWorkerUrl} from 'maplibre-gl';
import 'maplibre-gl/dist/maplibre-gl.css';
import workerUrl from 'maplibre-gl/dist/maplibre-gl-worker.mjs?worker&url';
import {renderToDom} from './src/app.tsx';
setWorkerUrl(workerUrl);
renderToDom(document.getElementById('map'));
</script>
</html>
2 changes: 1 addition & 1 deletion examples/maplibre/geojson-animation/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@
"react": "^18.0.0",
"react-dom": "^18.0.0",
"react-map-gl": "^8.0.0",
"maplibre-gl": "^5.0.0"
"maplibre-gl": "^6.0.0"
},
"devDependencies": {
"typescript": "^5.0.0",
Expand Down
Loading
Loading