Kepler.gl
Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.
Install / Use
/learn @keplergl/Kepler.glREADME
<img width="600" alt="Kepler.gl Demo" src="./screenshots/screenshot.png">
[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 18.18.2 (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 18.18.2 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
| Prop Name | Type | Default Value | Description |
| ----------------------------- | ------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| id | String | map | The unique identifier for the KeplerGl instance. Required when multiple KeplerGl instances exist. It maps to the state in the reducer (e.g. component with id foo can be found instate.keplerGl.foo). |
| mapboxApiAccessToken | String | undefined | API token for Mapbox, used for rendering base maps. Create a free token at Mapbox. |
| getState | Function | state => state.keplerGl | Function that specifies the path to the root KeplerGl state in the reducer. |
| width | Number | 800 | The width of the KeplerGl UI in pixels. |
| height | Number | 800 | The height of the KeplerGl UI in pixels. |
| appName | String | Kepler.Gl | The app name displayed in the side panel header. |
| version | String | v1.0 | The version displayed in the side panel header. |
| onSaveMap | Function | undefined | A function called when the "Save Map URL" in side panel header is clicked. |
| onViewStateChange | Function | undefined | Triggered when the map viewport is updated. Receives viewState parameter with updated values like longitude, latitude, zoom, etc. |
| getMapboxRef(mapbox, index) | Function | undefined | Called when KeplerGl adds or removes a MapContainer with an inner Mapbox map. mapbox is a MapRef when added, or null when removed. index is 0 for the first map and 1 for the second map in a split view. |
| actions | Object | {} | Custom action creators to override the default KeplerGl action creators. Only use custom action when you want to modify action payload. |
| mint | Boolean | true | Determines whether to load a fresh empty state when mounted. When false, the state persists acro
Related Skills
node-connect
347.2kDiagnose OpenClaw node connection and pairing failures for Android, iOS, and macOS companion apps
frontend-design
108.0kCreate distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
openai-whisper-api
347.2kTranscribe audio via OpenAI Audio Transcriptions API (Whisper).
qqbot-media
347.2kQQBot 富媒体收发能力。使用 <qqmedia> 标签，系统根据文件扩展名自动识别类型（图片/语音/视频/文件）。
