kepler.gl: WebGL Geospatial Visualization Component for Large Datasets

WebGL Rendering for Million-Point Geospatial Datasets

Traditional web map libraries render features on an HTML canvas or as SVG elements, which limits performance to tens of thousands of features before the browser slows down. kepler.gl takes a different approach: it uses WebGL through deck.gl to render directly on the GPU, which enables it to handle millions of points, trips, or aggregated cells at interactive frame rates in the browser.

The README describes it as capable of rendering millions of points representing thousands of trips and performing spatial aggregations on the fly. This makes it suited for datasets that would break a standard Leaflet or Mapbox GL JS visualization without tile-level pre-aggregation.

kepler.gl ships both as a standalone web application (available at kepler.gl/demo) and as a React component that can be embedded in existing applications. The standalone app provides a no-code interface for loading CSV, GeoJSON, and other spatial file formats and exploring them interactively. Version 3.3.0-alpha.15 was released on 28 September 2026, with the repository's last push on 25 September 2026.

The Rendering Stack: deck.gl, MapLibre GL, and Redux

kepler.gl is built on two libraries: MapLibre GL for the base map rendering and deck.gl for the data layer rendering on top.

MapLibre GL is an open-source fork of Mapbox GL JS that renders vector tiles and raster base maps using WebGL. deck.gl, developed by vis.gl (the same open-source organisation behind MapLibre contributions), provides a layering system for rendering large point clouds, arcs, trips, H3 hexagons, and other geospatial primitives on top of a map.

The application state is managed through Redux. The README describes kepler.gl as a React component that uses Redux to manage its internal state and data flow. Embedding the component requires mounting the kepler.gl reducer in your Redux store and including the task middleware that kepler.gl provides for async data loading.

The monorepo is structured as a yarn workspace with modules for each functional area: `@kepler.gl/components`, `@kepler.gl/reducers`, `@kepler.gl/layers`, `@kepler.gl/processors`, `@kepler.gl/effects`, `@kepler.gl/duckdb`, and `@kepler.gl/sqlrooms` are among the packages in the `src/` directory. Consumers install only the modules they need.

Installing kepler.gl and Getting a Mapbox Token

The component is published to npm as separate packages. To add the main UI component:

npm install --save @kepler.gl/components

Or with yarn:

yarn add @kepler.gl/components

For projects that do not use a module bundler, the README provides a precompiled UMD build. Add the script tag to an HTML file:

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

Or to pin a specific version:

<script src="https://unpkg.com/[email protected]/umd/keplergl.min.js" />

The README states that kepler.gl is built upon Mapbox and requires a Mapbox Access Token to render base maps. The `mapboxApiAccessToken` prop on the `KeplerGl` component receives this token. A free token can be created at mapbox.com. Teams who cannot use Mapbox will need to configure an alternative tile source.

For local development of kepler.gl itself, the README specifies Node 20.19.3 (from the `.nvmrc` file) and instructs contributors to run `nvm install` and `nvm use`. Newer Node versions can cause the `gl` dev dependency to fail compilation.

Embedding kepler.gl in a React Application

Integrating kepler.gl into a React-Redux application requires two steps: mounting the reducer and mounting the component.

The reducer setup from the README:

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

const reducers = combineReducers({
  keplerGl: keplerGlReducer,
  app: appReducer
});

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

The `enhanceReduxMiddleware` function adds the built-in task middleware that kepler.gl requires for async operations. Without it, data loading and async actions will not work.

With the reducer in place, mount the component:

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

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

The `id` prop identifies the kepler.gl instance in the Redux state tree. When multiple kepler.gl maps appear on the same page, each must have a unique id. The kepler.gl state for a component with `id="foo"` is accessible at `state.keplerGl.foo`. If the reducer is mounted at a non-root path, the `getState` prop tells the component where to find it, with the default being `state => state.keplerGl`.

Customization: Themes, Layer Types, and Reducer Extensions

The examples directory in the repository covers several extension patterns. There are separate example folders for custom layers, custom themes, custom reducers, custom map styles, and replacing individual UI components.

Layer types determine how data points are visualized: as scatter points, arcs, hex aggregations, trips, or other geometries. The `src/layers` package defines the built-in types. Custom layers can be added by extending the layer interface.

Theming is handled through a theme configuration passed to the component. The `examples/custom-theme` directory shows how to override the default visual style. The `examples/replace-component` directory shows how to substitute individual UI elements with custom implementations.

The `@kepler.gl/duckdb` package adds DuckDB integration, listed in the `src/duckdb` workspace. The `examples/duckdb-vite` example shows this in use. DuckDB enables in-browser SQL queries over large datasets, which is a meaningful addition for analytics workflows that want to filter or aggregate data client-side before passing it to the map layers.

The `examples/demo-app-sqlrooms` directory tests a collapsible shell layout using `@kepler.gl/sqlrooms`. This is run on port 8083 with `yarn start:sqlrooms`, parallel to the main demo on port 8080.

kepler.gl vs. QGIS, Leaflet, and Mapbox GL JS

The related searches show users comparing kepler.gl to QGIS, Leaflet, Mapbox GL JS, and MapLibre GL.

QGIS is a desktop GIS application that runs natively on Windows, macOS, and Linux. It handles complex spatial analysis workflows, raster data, and cartographic output. kepler.gl is browser-based and focused on exploratory data visualization of point and trip data. QGIS is the better tool for GIS analysis; kepler.gl is the better tool for browser-embedded geospatial exploration.

Leaflet is a lightweight JavaScript map library that renders SVG and Canvas elements. It is simple to use for standard map markers and polygons but reaches its performance ceiling much sooner than WebGL-based tools when the data volume grows. kepler.gl uses WebGL throughout and targets use cases where Leaflet would stall.

Mapbox GL JS renders vector tiles with WebGL and is the upstream source for MapLibre GL. kepler.gl is built on top of MapLibre GL (not directly on Mapbox GL JS), adding a full geospatial analysis UI, Redux state management, and built-in layer types. Mapbox GL JS is a lower-level map renderer; kepler.gl is a higher-level analytics application built above it.

Alpha Status, Limitations, and What the README Leaves Unsaid

The current release line is 3.3.0-alpha. Alpha versions signal that the API may change between releases. Teams who embed kepler.gl in production applications and upgrade regularly should watch the CHANGELOG and UPGRADE-GUIDE.md in the repository for breaking changes between alpha versions.

kepler.gl requires a Mapbox Access Token for base map rendering. The README does not document how to configure MapLibre GL with a free tile source as an alternative, so teams that want to avoid the Mapbox dependency must consult external documentation for tile provider configuration.

The monorepo structure with yarn workspaces means contributing to the project requires familiarity with the yarn workspace toolchain. The README notes that Node 20.19.3 is the specified version and that newer versions can break the `gl` dev dependency build.

kepler.gl has no built-in server component. Large dataset performance depends on the browser's WebGL capabilities and available GPU memory. Rendering millions of points works on a capable GPU, but the same dataset on a low-end device may hit memory limits. The README describes the rendering capability as client-side without server-side limitations, which is accurate for capable hardware but not universal.

Editorial conclusion

kepler.gl is the right tool for teams who need a browser-based map visualization component that can handle millions of geographic points without a backend aggregation service. The 3.3.0-alpha release line indicates the API is still moving, so projects that need stability should pin versions carefully. The Mapbox Access Token requirement for base maps adds an external dependency; teams who want to avoid Mapbox can explore MapLibre GL alternatives. The MIT licence permits commercial use and embedding without restrictions.

Frequently asked questions

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes