Guide · Open source
How to use kepler.gl: install, mount and embed it in React
Updated · written with AI from the project's own documentation and checked against our catalogue data
Kepler.gl is an open source, MIT-licensed tool for visually exploring large geolocation datasets on interactive maps. This guide covers what it is, how to install its npm modules, and how to mount it as a React component backed by Redux. By the end you will know the setup steps the README describes and which parts to check before you start.
kepler.glkeplergl/kepler.gl · ★ 12.1k · MIT Install options & downloads Quick start
- 1Confirm Node 20 or newer. Check that your project runs Node 20 or a newer supported LTS, since the README says older versions are not supported or tested.
- 2Install the modules. Run npm install --save @kepler.gl/components maplibre-gl or the yarn equivalent.
- 3Load the MapLibre stylesheet. Import maplibre-gl/dist/maplibre-gl.css once in your application entry point.
- 4Mount the kepler.gl reducer. Add keplerGl: keplerGlReducer to combineReducers and include enhanceReduxMiddleware in your store setup.
- 5Render the component. Import KeplerGl from @kepler.gl/components and render it with an id, width and height.
- 6Add a Mapbox token if needed. If you use Mapbox-hosted styles, pass mapboxApiAccessToken and load the mapbox-gl stylesheet.
What kepler.gl is and who it is for
Kepler.gl is a data-agnostic, web-based application for visual exploration of large-scale geolocation data sets. It is built on MapLibre GL and deck.gl, and the README says it can render millions of points representing thousands of trips and perform spatial aggregations on the fly.
It is also a React component that uses Redux to manage its state, so developers can embed it in their own React-Redux applications.
- Developers adding map-based data exploration to a React and Redux app
- Analysts who need to explore large location datasets visually in the browser
- Teams that already use MapLibre or Mapbox basemaps
Check the prerequisites before installing
When you use kepler.gl as a dependency in your own app, the README asks for Node 20 or a newer supported LTS. It says older Node versions are not supported or tested.
The README focuses on npm installs and embedding. If you need a no-code tool with no setup, the hosted demo at kepler.gl is the easier path. The latest release listed in the source is an alpha, so check the release status before relying on it in production.
- Node.js 20 or newer LTS
- npm or yarn for installing packages
Install the kepler.gl modules
Install the component package and maplibre-gl with npm or yarn. The README lists both commands as alternatives.
The default basemaps use MapLibre, so load its stylesheet once in your application entry point. If you only use Mapbox-hosted styles, install mapbox-gl and load its stylesheet instead. Apps that allow both should load both stylesheets.
npm install --save @kepler.gl/components maplibre-gl
// or
yarn add @kepler.gl/components maplibre-gl
import 'maplibre-gl/dist/maplibre-gl.css';Mount the reducer and middleware in Redux
Kepler.gl uses Redux for its internal state and a built-in task middleware for async side effects. Add the kepler.gl reducer under the key keplerGl in your combined reducers, and add taskMiddleware to your store. The easiest way is enhanceReduxMiddleware from @kepler.gl/reducers.
If you mount the reducer under a different key, or not at the root of your state, pass the path to the component with the getState prop.
- Import keplerGlReducer and enhanceReduxMiddleware from @kepler.gl/reducers
- Mount the reducer as keplerGl in combineReducers
- Wrap your middlewares with enhanceReduxMiddleware when creating the store
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';
const reducers = combineReducers({
keplerGl: keplerGlReducer,
app: appReducer
});Mount the KeplerGl component
Import KeplerGl from @kepler.gl/components and render it with an id, width, height and, if you use Mapbox styles, a mapboxApiAccessToken. The id maps to the state in the reducer, so a component with id foo is found at state.keplerGl.foo. Give each instance its own id when you have more than one.
The README says the mapboxApiAccessToken prop is used for rendering base maps and that you can create a token at Mapbox. The width and height props are in pixels, and the defaults are 800.
- id: required when multiple instances exist; defaults to map
- width and height: pixel sizes of the UI
- appName: text shown in the side panel header
import KeplerGl from '@kepler.gl/components';
const Map = props => (
<KeplerGl id="foo" width={width} mapboxApiAccessToken={token} height={height} />
);Use the UMD build without a bundler
If you do not use a module bundler, the npm package includes precompiled production UMD builds. Load the MapLibre stylesheet and the kepler.gl script tag in your HTML file. You can load the latest version or pin a specific one, as the README shows with a version 3 example.
The UMD script tags are the README's no-bundler route. Pinning a version keeps your page stable when new releases appear.
<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" />What people use it for
- Embedding a map-based data exploration panel inside a React and Redux dashboard
- Letting analysts visually explore large location datasets in the browser
- Rendering millions of points or trip data with on-the-fly spatial aggregation
Frequently asked questions
Is kepler.gl free to use?
The repository is licensed under the MIT License, as shown in the README badges and project metadata. The source does not list any pricing. If you use Mapbox-hosted basemaps, the README notes you can create a free token at Mapbox.
How do I install kepler.gl?
The README gives npm install --save @kepler.gl/components maplibre-gl or yarn add with the same packages. It is a package-manager install, and you must also import the MapLibre stylesheet in your app.
What Node version does kepler.gl need?
When using kepler.gl as a dependency, the README asks for Node 20 or a newer supported LTS. Older Node versions are not supported or tested.
Can I use kepler.gl without React?
The source describes kepler.gl as a React component and also provides precompiled UMD builds for use without a module bundler, loaded via script tag in an HTML file. The README does not describe other framework bindings.
Why does my map show no basemap or fail to load?
The README says the default basemaps use MapLibre, so the MapLibre stylesheet must be loaded. If you use Mapbox-hosted styles, install mapbox-gl, load its stylesheet, and pass a mapboxApiAccessToken. The source does not list other troubleshooting steps.
Is there a stable release I can rely on?
The latest release listed in the source is an alpha, so the project may not have a stable release yet. Check the release status before depending on it in production.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Kepler.gl suits developers who want to embed large-scale map exploration in a React and Redux app, and analysts who are comfortable with a Node setup. If you need a no-code tool or a stable release, use the hosted demo or pick a different tool, since the latest listed release is an alpha.
Install options & downloads