Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

fix(examples): load required MapLibre CSS (#3820)

Igor Dykhtac211c82288b2
diff --git a/README.md b/README.md
index c2e019a7e..331833372 100644
--- a/README.md
+++ b/README.md
@@ -60,23 +60,34 @@ When **using kepler.gl as a dependency** in your own app, use Node 20 or a newer
Kepler.gl consists of different modules. Each module can be added to the project like this:
```sh
-npm install --save @kepler.gl/components
+npm install --save @kepler.gl/components maplibre-gl
// or
-yarn add @kepler.gl/components
+yarn add @kepler.gl/components maplibre-gl
```
-kepler.gl is built upon [mapbox][mapbox]. You will need a [Mapbox Access Token][mapbox-token] to use it.
+The default basemaps use MapLibre. Load its stylesheet once in your application entry point:
+
+```js
+import 'maplibre-gl/dist/maplibre-gl.css';
+```
+
+If your application only uses Mapbox-hosted styles, install `mapbox-gl` and load
+`mapbox-gl/dist/mapbox-gl.css` instead. Applications that allow both MapLibre and
+Mapbox styles should load both stylesheets.
If you don't use a module bundler, it's also fine. Kepler.gl npm package includes precompiled production UMD builds in the [umd folder](https://unpkg.com/kepler.gl/umd).
-You can add the script tag to your html file as it follows (latest version of Kepler.gl):
+Load the MapLibre stylesheet and add the script tag to your HTML file as follows
+(latest version of Kepler.gl):
```html
+<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^4/dist/maplibre-gl.css" />
<script src="https://unpkg.com/kepler.gl/umd/keplergl.min.js" />
```
or if you would like, you can load a specific version:
```html
+<link rel="stylesheet" href="https://unpkg.com/maplibre-gl@^3/dist/maplibre-gl.css" />
<script src="https://unpkg.com/[email protected]/umd/keplergl.min.js" />
```
diff --git a/docs/api-reference/get-started.md b/docs/api-reference/get-started.md
index 205a24275..0da26a7fd 100644
--- a/docs/api-reference/get-started.md
+++ b/docs/api-reference/get-started.md
@@ -5,12 +5,32 @@
Use <b>Node v20</b> and above, older node versions have not been tested
```sh
-npm install --save kepler.gl @kepler.gl/components @kepler.gl/reducers
+npm install --save kepler.gl @kepler.gl/components @kepler.gl/reducers maplibre-gl
```
-### Get Mapbox Token
+The default basemaps use MapLibre, so load its stylesheet once in your application entry point:
-Kepler.gl is built on top of [Mapbox GL](https://www.mapbox.com). A mapbox account and an access token are needed to use kepler.gl in your app. Get a [Mapbox Access Token](https://www.mapbox.com/help/define-access-token/) at mapbox.com.
+```js
+import 'maplibre-gl/dist/maplibre-gl.css';
+```
+
+Mapbox-only applications should load `mapbox-gl/dist/mapbox-gl.css` instead.
+Applications that allow both MapLibre and Mapbox styles should load both stylesheets.
+
+For a Mapbox-only application, replace `maplibre-gl` in the installation command:
+
+```sh
+npm install --save kepler.gl @kepler.gl/components @kepler.gl/reducers mapbox-gl
+```
+
+```js
+import 'mapbox-gl/dist/mapbox-gl.css';
+```
+
+### Get a Mapbox Token (Mapbox styles only)
+
+The default MapLibre-backed basemaps do not require a Mapbox token. If your application uses
+Mapbox-hosted styles, create a Mapbox account and get a [Mapbox Access Token](https://www.mapbox.com/help/define-access-token/).
### Basic Usage
@@ -30,6 +50,7 @@ import { connect, Provider } from "react-redux";
import keplerGlReducer, { enhanceReduxMiddleware } from "@kepler.gl/reducers";
import KeplerGl from "@kepler.gl/components";
+import "maplibre-gl/dist/maplibre-gl.css";
import AutoSizer from "react-virtualized/dist/commonjs/AutoSizer";
diff --git a/examples/clicked-feature/package.json b/examples/clicked-feature/package.json
index aa38ef4ba..69c0d556a 100644
--- a/examples/clicked-feature/package.json
+++ b/examples/clicked-feature/package.json
@@ -14,6 +14,7 @@
"@kepler.gl/processors": "^3.3.0-alpha.6",
"@kepler.gl/reducers": "^3.3.0-alpha.6",
"@kepler.gl/utils": "^3.3.0-alpha.6",
+ "maplibre-gl": "^4.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-redux": "^9.1.0",
diff --git a/examples/clicked-feature/src/app.tsx b/examples/clicked-feature/src/app.tsx
index 2b5a9a937..aa76228b6 100644
--- a/examples/clicked-feature/src/app.tsx
+++ b/examples/clicked-feature/src/app.tsx
@@ -6,6 +6,7 @@ import {useState, useEffect} from 'react';
import ReactDOM from 'react-dom/client';
import {Provider, useDispatch, useSelector} from 'react-redux';
import {applyMiddleware, combineReducers, compose, createStore} from 'redux';
+import 'maplibre-gl/dist/maplibre-gl.css';
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
import KeplerGl from '@kepler.gl/components';
diff --git a/examples/clicked-feature/src/index.html b/examples/clicked-feature/src/index.html
index 9a3bddf86..5c7504a8f 100644
--- a/examples/clicked-feature/src/index.html
+++ b/examples/clicked-feature/src/index.html
@@ -7,6 +7,7 @@
html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
#root { width: 100%; height: 100%; }
</style>
+ <link rel="stylesheet" href="./bundle.css" />
</head>
<body>
<div id="root" />
diff --git a/examples/custom-layer/package.json b/examples/custom-layer/package.json
index ba9362481..65cc03b04 100644
--- a/examples/custom-layer/package.json
+++ b/examples/custom-layer/package.json
@@ -14,6 +14,7 @@
"@kepler.gl/components": "^3.3.0-alpha.6",
"@kepler.gl/layers": "^3.3.0-alpha.6",
"@kepler.gl/reducers": "^3.3.0-alpha.6",
+ "maplibre-gl": "^4.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-redux": "^9.1.0",
diff --git a/examples/custom-layer/src/app.tsx b/examples/custom-layer/src/app.tsx
index 199330954..8795deeb3 100644
--- a/examples/custom-layer/src/app.tsx
+++ b/examples/custom-layer/src/app.tsx
@@ -6,6 +6,7 @@ import {useState, useEffect} from 'react';
import ReactDOM from 'react-dom/client';
import {Provider, useDispatch} from 'react-redux';
import {applyMiddleware, combineReducers, compose, createStore} from 'redux';
+import 'maplibre-gl/dist/maplibre-gl.css';
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
import KeplerGl, {injectComponents, LayerConfiguratorFactory} from '@kepler.gl/components';
diff --git a/examples/custom-layer/src/index.html b/examples/custom-layer/src/index.html
index 2d2dc6582..a204b707a 100644
--- a/examples/custom-layer/src/index.html
+++ b/examples/custom-layer/src/index.html
@@ -7,6 +7,7 @@
html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
#root { width: 100%; height: 100%; }
</style>
+ <link rel="stylesheet" href="./bundle.css" />
</head>
<body>
<div id="root" />
diff --git a/examples/duckdb-vite/package.json b/examples/duckdb-vite/package.json
index a277cabab..b0a7e0e18 100644
--- a/examples/duckdb-vite/package.json
+++ b/examples/duckdb-vite/package.json
@@ -15,6 +15,7 @@
"@kepler.gl/styles": "^3.3.0-alpha.15",
"@kepler.gl/types": "^3.3.0-alpha.15",
"@kepler.gl/utils": "^3.3.0-alpha.15",
+ "maplibre-gl": "^4.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-redux": "^9.1.0",
diff --git a/examples/duckdb-vite/src/main.tsx b/examples/duckdb-vite/src/main.tsx
index 40d655097..13c7c0906 100644
--- a/examples/duckdb-vite/src/main.tsx
+++ b/examples/duckdb-vite/src/main.tsx
@@ -7,6 +7,7 @@ import {Provider, useSelector} from 'react-redux';
import {applyMiddleware, combineReducers, compose, createStore} from 'redux';
import styled, {ThemeProvider} from 'styled-components';
import {Panel, PanelGroup, PanelResizeHandle} from 'react-resizable-panels';
+import 'maplibre-gl/dist/maplibre-gl.css';
import {injectComponents} from '@kepler.gl/components';
import {SqlPanel} from '@kepler.gl/duckdb/components';
diff --git a/examples/get-started-vite/package.json b/examples/get-started-vite/package.json
index f4b7e0ff6..070dbf990 100644
--- a/examples/get-started-vite/package.json
+++ b/examples/get-started-vite/package.json
@@ -11,6 +11,7 @@
"@deck.gl/mapbox": "9.3.1",
"@kepler.gl/components": "^3.3.0-alpha.6",
"@kepler.gl/reducers": "^3.3.0-alpha.6",
+ "maplibre-gl": "^4.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-redux": "^9.1.0",
diff --git a/examples/get-started-vite/src/main.tsx b/examples/get-started-vite/src/main.tsx
index b22896917..e214ac589 100644
--- a/examples/get-started-vite/src/main.tsx
+++ b/examples/get-started-vite/src/main.tsx
@@ -5,6 +5,7 @@ import React, {useState, useEffect} from 'react';
import ReactDOM from 'react-dom/client';
import {Provider, useDispatch} from 'react-redux';
import {applyMiddleware, combineReducers, compose, createStore} from 'redux';
+import 'maplibre-gl/dist/maplibre-gl.css';
import KeplerGl from '@kepler.gl/components';
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
diff --git a/examples/get-started/package.json b/examples/get-started/package.json
index 877df4abc..b2123273c 100644
--- a/examples/get-started/package.json
+++ b/examples/get-started/package.json
@@ -11,6 +11,7 @@
"@deck.gl/mapbox": "9.3.1",
"@kepler.gl/components": "^3.3.0-alpha.6",
"@kepler.gl/reducers": "^3.3.0-alpha.6",
+ "maplibre-gl": "^4.0.0",
"react": "^19.0.0",
"react-dom": "^19.0.0",
"react-redux": "^9.1.0",
diff --git a/examples/get-started/src/app.tsx b/examples/get-started/src/app.tsx
index d15e95ffb..cc027472a 100644
--- a/examples/get-started/src/app.tsx
+++ b/examples/get-started/src/app.tsx
@@ -6,6 +6,7 @@ import {useState, useEffect} from 'react';
import ReactDOM from 'react-dom/client';
import {Provider, useDispatch} from 'react-redux';
import {applyMiddleware, combineReducers, compose, createStore} from 'redux';
+import 'maplibre-gl/dist/maplibre-gl.css';
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
import KeplerGl from '@kepler.gl/components';
diff --git a/examples/get-started/src/index.html b/examples/get-started/src/index.html
index 65c461b20..0dedf9cc7 100644
--- a/examples/get-started/src/index.html
+++ b/examples/get-started/src/index.html
@@ -7,6 +7,7 @@
html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
#root { width: 100%; height: 100%; }
</style>
+ <link rel="stylesheet" href="./bundle.css" />
</head>
<body>
<div id="root" />
diff --git a/examples/live-data/src/app.tsx b/examples/live-data/src/app.tsx
index f9575d0cc..5bfad6be0 100644
--- a/examples/live-data/src/app.tsx
+++ b/examples/live-data/src/app.tsx
@@ -6,6 +6,7 @@ import {useCallback, useEffect, useRef, useState} from 'react';
import ReactDOM from 'react-dom/client';
import {Provider, useDispatch, useSelector} from 'react-redux';
import {applyMiddleware, combineReducers, compose, createStore} from 'redux';
+import 'maplibre-gl/dist/maplibre-gl.css';
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
import KeplerGl from '@kepler.gl/components';
diff --git a/examples/live-data/src/index.html b/examples/live-data/src/index.html
index e8138c189..f441c9223 100644
--- a/examples/live-data/src/index.html
+++ b/examples/live-data/src/index.html
@@ -7,6 +7,7 @@
html, body { margin: 0; padding: 0; width: 100%; height: 100%; overflow: hidden; }
#root { width: 100%; height: 100%; }
</style>
+ <link rel="stylesheet" href="./bundle.css" />
</head>
<body>
<div id="root" />