Skip to content

Kepler.gl is a powerful open source geospatial analysis tool for large-scale data sets.

Improved Props and Gettings Started Docs (#2993)

ironicbrew7e2db2b7dec7
diff --git a/README.md b/README.md
index ff5729faf..665086c18 100644
--- a/README.md
+++ b/README.md
@@ -149,122 +149,32 @@ const Map = props => (
);
```
-#### Props
-
-##### `id` (String, required)
-
-- Default: `map`
-
-The id of this KeplerGl instance. `id` is required if you have multiple
-KeplerGl instances in your app. It defines the prop name of the KeplerGl state that is
-stored in the KeplerGl reducer. For example, the state of the KeplerGl component with id `foo` is
-stored in `state.keplerGl.foo`.
-
-In case you create multiple kepler.gl instances using the same id, the kepler.gl state defined by the entry will be
-overridden by the latest instance and reset to a blank state.
-
-##### `mapboxApiAccessToken` (String, required\*)
-
-- Default: `undefined`
-
-By default, kepler.gl uses mapbox-gl.js to render its base maps. You can create a free account at [mapbox][mapbox] and create a token at [www.mapbox.com/account/access-tokens][mapbox-token].
-
-If you replaced kepler.gl default map styles with your own, and they are not Mapbox styles. `mapboxApiAccessToken` will not be required.
-
-Read more about [Custom Map Styles][custom-map-styles].
-
-##### `getState` (Function, optional)
-
-- Default: `state => state.keplerGl`
-
-The path to the root keplerGl state in your reducer.
-
-##### `width` (Number, optional)
-
-- Default: `800`
-
-Width of the KeplerGl UI.
-
-##### `height` (Number, optional)
-
-- Default: `800`
-
-##### `appName` (String, optional)
-
-- Default: `Kepler.Gl`
-
-App name displayed in side panel header
-
-##### `version` (String, optional)
-
-- Default: `v1.0`
-
-version displayed in side panel header
-
-##### `onSaveMap` (Function, optional)
-
-- Default: `undefined`
-
-Action called when click Save Map Url in side panel header.
-
-##### `onViewStateChange` (Function, optional)
-
-- Default: `undefined`
-- Parameter: `viewState` - An updated view state object containing parameters such as longitude, latitude, zoom etc
-
-Action triggered when map viewport is updated.
-
-##### `getMapboxRef(mapbox, index)` (Function, optional)
-
-- Default: `undefined`
-
-Function called when `KeplerGL` adds or removes a `MapContainer` component having an inner Mapbox map.
-
-The `mapbox` argument is an [`MapRef`](https://visgl.github.io/react-map-gl/docs/api-reference/types#mapref) when added or `null` when removed.
-
-The `index` argument is 0 for a single map or 1 for an additional map (since `KeplerGL` supports an optional split map view).
-
-##### `actions` (Object, optional)
-
-- Default: `{}`
-
-Actions creators to replace default kepler.gl action creator. Only use custom action when you want to modify action payload.
-
-##### `mint` (Boolean, optional)
-
-- Default: `true`
-
-Whether to load a fresh empty state when component is mounted. when parse `mint: true` kepler.gl component will always load a fresh state when re-mount the same component, state inside this component will be destroyed once its unmounted.
-By Parsing `mint: false` kepler.gl will keep the component state in the store even when it is unmounted, and use it as initial state when re-mounted again. This is useful when mounting kepler.gl in a modal, and keep the same map when re-open.
-
-Read more about [Components][components].
-
-##### `theme` (Object | String, optional)
-
-- default: `null`
-
-One of `"dark"`, `"light"` or `"base"`
-You can pass theme name or object used to customize Kepler.gl style. Kepler.gl provide an `'light'` theme besides the default 'dark' theme. When pass in a theme object Kepler.gl will use the value passed as input to override values from [theme](https://github.com/keplergl/kepler.gl/blob/master/src/styles/base.js).
-
-Read more about [Custom Theme][custom-theme]
-
-#### `mapboxApiUrl` (String, optional)
-
-- Default: `https://api.mapbox.com`
-
-If you are using your own mapbox tile server, you can pass in your own tile server api url.
-
-#### `mapStylesReplaceDefault` (Boolean, optional)
-
-- Default: `false`
-
-kepler.gl provide 4 map styles to choose from. Pass `true` if you want to supply your own `mapStyles`. See Below.
-
-#### `mapStyles` (Array, optional)
-
-- Default: `[]`
-
-You can supply additional map styles to be displayed in [map style selection panel](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/1-base-map-styles.md). By default, additional map styles will be added to default map styles. If 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](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/2-map-layers.md). Supply your own `layerGroups` to override default for more accurate layer grouping.
+### 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 in`state.keplerGl.foo`). |
+| `mapboxApiAccessToken` | String | `undefined` | API token for Mapbox, used for rendering base maps. Create a free token at [Mapbox](https://www.mapbox.com). |
+| `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 across remounts. Useful for modal use cases. |
+| `theme` | Object/String| `null` | Set to `"dark"`, `"light"`, or `"base"`, or pass a theme object to customize KeplerGl’s style. |
+| `mapboxApiUrl` | String | `https://api.mapbox.com` | The Mapbox API URL if you are using a custom Mapbox tile server. |
+| `mapStylesReplaceDefault` | Boolean | `false` | Set to `true` to replace default map styles with custom ones. (see ```mapStyles``` prop) |
+| `mapStyles` | Array | `[]` | An array of [custom map styles](#example-custom-map-style) for the map style selection panel. Styles replace the default ones if `mapStylesReplaceDefault` is `true`. |
+| `initialUiState` | Object | `undefined` | The initial UI state applied to the `uiState` reducer. |
+| `localeMessages` | Object | `undefined` | Used to modify or add new translations. Read more about [Localization][localization]. |
+
+#### Example Custom Map Style
+
+You can supply additional map styles to be displayed in [map style selection panel](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/1-base-map-styles.md). 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](https://github.com/keplergl/kepler.gl/blob/master/docs/user-guides/f-map-styles/2-map-layers.md). Supply your own `layerGroups` to override default for more accurate layer grouping.
Each `mapStyles` should has the following properties:
@@ -288,7 +198,6 @@ const mapStyles = [
defaultVisibility: true
},
{
- // adding this will keep the 3d building option
slug: '3d building',
filter: () => false,
defaultVisibility: false
@@ -298,20 +207,6 @@ const mapStyles = [
];
```
-Read more about [Custom Map Styles][custom-map-styles].
-
-#### `initialUiState` (object, optional)
-
-- Default: `undefined`
-
-Intial UI State applied to uiState reducer, value will be shallow merged with default [`INITIAL_UI_STATE`](https://docs.kepler.gl/docs/api-reference/reducers/ui-state#initial_ui_state)
-
-#### `localeMessages` (object, optional)
-
-- Default: `undefined` Modify default translation or add new translation
-
-Read more about [Localization][localization].
-
### 3. Dispatch custom actions to `keplerGl` reducer.
One advantage of using the reducer over React component state to handle keplerGl state is the flexibility
diff --git a/docs/api-reference/get-started.md b/docs/api-reference/get-started.md
index 5a17d8e3f..e86cbc135 100644
--- a/docs/api-reference/get-started.md
+++ b/docs/api-reference/get-started.md
@@ -16,6 +16,77 @@ Kepler.gl is built on top of [Mapbox GL](https://www.mapbox.com). A mapbox accou
![Basic Usage][basic-usage]
+#### 0. Working Template
+
+```js
+import * as React from "react";
+import ReactDOM from "react-dom/client";
+import document from "global/document";
+
+import { applyMiddleware, combineReducers, compose, createStore } from "redux";
+import { connect, Provider } from "react-redux";
+
+import keplerGlReducer, { enhanceReduxMiddleware } from "@kepler.gl/reducers";
+import KeplerGl from "@kepler.gl/components";
+
+import AutoSizer from "react-virtualized/dist/commonjs/AutoSizer";
+
+const reducers = combineReducers({
+ keplerGl: keplerGlReducer.initialState({
+ uiState: {
+ readOnly: false,
+ currentModal: null,
+ },
+ }),
+});
+
+const middleWares = enhanceReduxMiddleware([
+ // Add other middlewares here
+]);
+
+const enhancers = applyMiddleware(...middleWares);
+
+const initialState = {};
+const store = createStore(reducers, initialState, compose(enhancers));
+
+const App2 = () => (
+ <div
+ style={{
+ position: "absolute",
+ top: "0px",
+ left: "0px",
+ width: "100%",
+ height: "100%",
+ }}
+ >
+ <AutoSizer>
+ {({ height, width }) => (
+ <KeplerGl
+ mapboxApiAccessToken="xxx" // Replace with your mapbox token
+ id="map"
+ width={width}
+ height={height}
+ />
+ )}
+ </AutoSizer>
+ </div>
+);
+
+const mapStateToProps = (state) => state;
+const dispatchToProps = (dispatch) => ({ dispatch });
+const ConnectedApp = connect(mapStateToProps, dispatchToProps)(App2);
+const Root = () => (
+ <Provider store={store}>
+ <App2 />
+ </Provider>
+);
+
+export default Root;
+```
+
+
+
+
#### 1. Mount reducer
Kepler.gl uses [Redux](https://redux.js.org/) to manage its internal state, along with [react-palm](https://github.com/btford/react-palm) middleware to handle side effects. Mount kepler.gl reducer in your store, apply `taskMiddleware`.