kepler.gl | Website | Demo App | Docs

[Kepler.gl][web] 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][web]
• [Demo][demo-app]
• [Examples][examples]
• [Get Started][get-started]
• [App User Guide][user-guide]
• [Jupyter Widget User Guide][user-guide-jupyter]
• [Documentation][docs]
• [Stack Overflow][stack]
• [Contribution Guidelines][contributing]
• [Api Reference][api-reference]
• [Roadmap][roadmap]

Env

For developing this repository, use Node 20.19.3 (see .nvmrc): run nvm install and nvm use. Newer Node versions can make yarn install / yarn bootstrap try to compile the gl dev dependency from source; if that fails, see Troubleshooting: gl package install.

When using kepler.gl as a dependency in your own app, use Node 20.19.3 or a 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
// or
yarn add @kepler.gl/components

kepler.gl is built upon [mapbox][mapbox]. You will need a [Mapbox Access Token][mapbox-token] to use it.

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. You can add the script tag to your html file as it follows (latest version of Kepler.gl):

<script src="https://unpkg.com/kepler.gl/umd/keplergl.min.js" />

or if you would like, you can load a specific version:

<script src="https://unpkg.com/kepler.gl@3.0.0/umd/keplergl.min.js" />

Develop kepler.gl

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

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 [react-palm][react-palm] middleware to handle side effects.

You need to add taskMiddleware of react-palm to your store too. We are actively working on a solution where react-palm will not be required, however it is still a very lightweight side effects management tool that is easier to test than react-thunk.

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

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][reducers].

2. Mount Component

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

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

Props

Example Custom Map Style

You can supply additional map styles to be displayed in map style selection panel. By default, additional map styles will be added to default map styles. If you pass mapStylesReplaceDefault: true, they will replace the default ones. kepler.gl will attempt to group layers of your style based on its id naming convention and use it to allow toggle visibility of base map layers. Supply your own layerGroups to override default for more accurate layer grouping.

Each mapStyles should has the following properties:

• id (String, required) unique string that should not be one of these reserved dark light muted. muted_night
• label (String, required) name to be displayed in map style selection panel
• url (String, required) mapbox style url or a url pointing to the map style json object written in Mapbox GL Style Spec.
• icon (String, optional) image icon of the style, it can be a url, or an image data url
• layerGroups (Array, optional)

const mapStyles = [
  {
    id: 'my_dark_map',
    label: 'Dark Streets 9',
    url: 'mapbox://styles/mapbox/dark-v9',
    icon: `${apiHost}/styles/v1/mapbox/dark-v9/static/-122.3391,37.7922,9.19,0,0/400x300?access_token=${accessToken}&logo=false&attribution=false`,
    layerGroups: [
      {
        slug: 'label',
        filter: ({id}) => id.match(/(?=(label|place-|poi-))/),
        defaultVisibility: true
      },
      {
        slug: '3d building',
        filter: () => false,
        defaultVisibility: false
      }
    ]
  }
];

3. Dispatch custom actions to keplerGl reducer.

One advantage of using the reducer over React component state to handle keplerGl state is the flexibility to customize its behavior. If you only have one KeplerGl instance