Large-scale WebGL-powered Geospatial Data Visualization Tool

Kepler.gl is a data-agnostic, high-performance web-based application for visual exploration of large-scale geolocation data sets. Built on top of MapLibre GL and deck.gl, kepler.gl can render millions of points representing thousands of trips and perform spatial aggregations on the fly.

Kepler.gl is also a React component that uses Redux to manage its state and data flow. It can be embedded into other React-Redux applications and is highly customizable. For information on how to embed kepler.gl in your app take a look at the documentation.

Links

• Website
• Demo
• Examples
• Get Started
• App User Guide
• Jupyter Widget User Guide
• AI assistants and MCP
• Documentation
• Stack Overflow
• Contribution Guidelines
• Api Reference
• Roadmap

AI assistants and MCP

Use Codex, Claude Code, or another MCP client to control a live kepler.gl map: load data, configure layers, apply filters, manage bookmarks, and play camera tours. The client connects through a local MCP bridge to an open map tab.

Follow the MCP setup guide for a local checkout, including Codex configuration and connecting the browser. You can also install the kepler.gl skills for guidance on working with the app or creating maps with the Python package.

Env

For developing this repository, use Node 24.21.0 (see .nvmrc): run nvm install and nvm use. yarn install / yarn bootstrap compile the gl dev dependency from source on this pin, because [email protected] does not publish a Node 24 prebuild. If that compile fails, see Troubleshooting: gl package install.

When using kepler.gl as a dependency in your own app, use Node 20 or a newer supported LTS. Older Node versions are not supported or tested.

Install kepler.gl modules

Kepler.gl consists of different modules. Each module can be added to the project like this:

npm install --save @kepler.gl/components maplibre-gl
// or
yarn add @kepler.gl/components maplibre-gl

The default basemaps use MapLibre. Load its stylesheet once in your application entry point:

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. Load the MapLibre stylesheet and add the script tag to your HTML file as follows (latest version of Kepler.gl):

<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:

<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" />

Develop kepler.gl

Take a look at the development guide to develop kepler.gl locally.

The SQLRooms demo tests a collapsible application shell and modular panel layout using @kepler.gl/sqlrooms. Run it with yarn start:sqlrooms (port 8083), alongside the original main demo with yarn start (port 8080). The website continues to serve the original app at /demo.

Basic Usage

Here are the basic steps to import kepler.gl into your app. You also take a look at the examples folder. Each example in the folder can be installed and run locally.

1. Mount reducer

Kepler.gl uses Redux to manage its internal state, along with a built-in task middleware to handle async side effects.

You need to add taskMiddleware to your store. The easiest way is via enhanceReduxMiddleware from @kepler.gl/reducers:

import {createStore, combineReducers, applyMiddleware, compose} from 'redux';
import keplerGlReducer, {enhanceReduxMiddleware} from '@kepler.gl/reducers';

const initialState = {};
const reducers = combineReducers({
  // <-- mount kepler.gl reducer in your app
  keplerGl: keplerGlReducer,

  // Your other reducers here
  app: appReducer
});

// using createStore
export default createStore(
  reducer,
  initialState,
  applyMiddleware(
    enhanceReduxMiddleware([
      /* Add other middlewares here */
    ])
  )
);

Or if use enhancer:

// using enhancers
const initialState = {};
const middlewares = enhanceReduxMiddleware([
  // Add other middlewares here
]);
const enhancers = [applyMiddleware(...middlewares)];

export default createStore(reducer, initialState, compose(...enhancers));

If you mount kepler.gl reducer in another address instead of keplerGl, or the kepler.gl reducer is not mounted at root of your state, you will need to specify the path to it when you mount the component with the getState prop.

Read more about Reducers.

2. Mount Component

import KeplerGl from '@kepler.gl/components';

const Map = props => (
  <KeplerGl id="foo" width={width} mapboxApiAccessToken={token} height={height} />
);

This is the beginning of the README. Read the rest at the original. Read the full README ↗