Skip to content

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

Update grammar, cleanup whitespace, fix broken link (#912)

Jon Sadka40b92e56ad27
diff --git a/README.md b/README.md
index 7525bcfc2..b0f890411 100644
--- a/README.md
+++ b/README.md
@@ -262,35 +262,37 @@ kepler.gl provide 4 map styles to choose from. Pass `true` if you want to supply
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.
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
- - `icon` (String, optional) image icon of the style, it can be a url, or an [image data url](https://flaviocopes.com/data-urls/#how-does-a-data-url-look)
- - `layerGroups` (Array, optional)
+
+- `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
+- `icon` (String, optional) image icon of the style, it can be a url, or an [image data url](https://flaviocopes.com/data-urls/#how-does-a-data-url-look)
+- `layerGroups` (Array, optional)
```js
- 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: [{
+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
- }, {
+ },
+ {
// adding this will keep the 3d building option
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
@@ -533,24 +535,26 @@ Read more about [replacing UI component][replace-ui-component]
### 6. How to add data to map
-To interact with a kepler.gl instance and add new data to it, you can dispatch **`addDataToMap`** action from anywhere inside your app. It adds a dataset or multiple datasets to kepler.gl instance and update the full configuration (mapState, mapStyle, visState).
+To interact with a kepler.gl instance and add new data to it, you can dispatch the **`addDataToMap`** action from anywhere inside your app. It adds a dataset or multiple datasets to a kepler.gl instance and updates the full configuration (mapState, mapStyle, visState).
#### Parameters
-- `datasets` **([Array][41]<[Object][40]> | [Object][40])** **\*required** datasets can be a dataset or an array of datasets
- Each dataset object needs to have `info` and `data` property.
- - `datasets.info` **[Object][40]** \-info of a dataset
- - `datasets.info.id` **[string][42]** id of this dataset. If config is defined, `id` should matches the `dataId` in config.
- - `datasets.info.label` **[string][42]** A display name of this dataset
- - `datasets.data` **[Object][40]** **\*required** The data object, in a tabular format with 2 properties `fields` and `rows`
- - `datasets.data.fields` **[Array][41]<[Object][40]>** **\*required** Array of fields,
- - `datasets.data.fields.name` **[string][42]** **\*required** Name of the field,
- - `datasets.data.rows` **[Array][41]<[Array][41]>** **\*required** Array of rows, in a tabular format with `fields` and `rows`
-- `options` **[Object][40]**
- - `options.centerMap` **[boolean][43]** `default: true` if `centerMap` is set to `true` kepler.gl will place the map view within the data points boundaries
- - `options.readOnly` **[boolean][43]** `default: false` if `readOnly` is set to `true`
- the left setting panel will be hidden
- - `options.keepExistingConfig` **[boolean][43]** `default: false` whether to keep exiting map config, including layers, filters and splitMaps.
+- `data` **[Object][40]** **\*required**
+ - `datasets` **([Array][41]<[Object][40]> | [Object][40])** **\*required** datasets can be a dataset or an array of datasets
+ Each dataset object needs to have `info` and `data` property.
+ - `datasets.info` **[Object][40]** \-info of a dataset
+ - `datasets.info.id` **[string][42]** id of this dataset. If config is defined, `id` should matches the `dataId` in config.
+ - `datasets.info.label` **[string][42]** A display name of this dataset
+ - `datasets.data` **[Object][40]** **\*required** The data object, in a tabular format with 2 properties `fields` and `rows`
+ - `datasets.data.fields` **[Array][41]<[Object][40]>** **\*required** Array of fields,
+ - `datasets.data.fields.name` **[string][42]** **\*required** Name of the field,
+ - `datasets.data.rows` **[Array][41]<[Array][41]>** **\*required** Array of rows, in a tabular format with `fields` and `rows`
+ - `options` **[Object][40]**
+
+ - `options.centerMap` **[boolean][43]** `default: true` if `centerMap` is set to `true` kepler.gl will place the map view within the data points boundaries
+ - `options.readOnly` **[boolean][43]** `default: false` if `readOnly` is set to `true`
+ the left setting panel will be hidden
+ - `options.keepExistingConfig` **[boolean][43]** `default: false` whether to keep exiting map config, including layers, filters and splitMaps.
- `config` **[Object][40]** this object will contain the full kepler.gl instance configuration {mapState, mapStyle, visState}
diff --git a/docs/api-reference/actions/actions.md b/docs/api-reference/actions/actions.md
index e27e887d2..8da3dd52a 100644
--- a/docs/api-reference/actions/actions.md
+++ b/docs/api-reference/actions/actions.md
@@ -244,7 +244,7 @@ Input a custom map style object
**Parameters**
-- `inputStyle` **[Object][154]**
+- `inputStyle` **[Object][154]**
- `inputStyle.url` **[string][152]** style url e.g. `'mapbox://styles/heshan/xxxxxyyyyzzz'`
- `inputStyle.id` **[string][152]** style url e.g. `'custom_style_1'`
- `inputStyle.style` **[Object][154]** actual mapbox style json
@@ -261,10 +261,10 @@ Callback when a custom map style object is received
**Parameters**
-- `customMapStyle` **[Object][154]**
- - `customMapStyle.icon` **[string][152]**
- - `customMapStyle.style` **[Object][154]**
- - `customMapStyle.error` **any**
+- `customMapStyle` **[Object][154]**
+ - `customMapStyle.icon` **[string][152]**
+ - `customMapStyle.style` **[Object][154]**
+ - `customMapStyle.error` **any**
### loadMapStyleErr
@@ -275,7 +275,7 @@ Callback when load map style error
**Parameters**
-- `error` **any**
+- `error` **any**
### loadMapStyles
@@ -319,7 +319,7 @@ Request map style style object based on style.url.
**Parameters**
-- `mapStyles` **[Array][164]<[Object][154]>**
+- `mapStyles` **[Array][164]<[Object][154]>**
### set3dBuildingColor
@@ -340,7 +340,7 @@ is listened by all subreducers,
### addDataToMap
Add data to kepler.gl reducer, prepare map with preset configuration if config is passed.
-Kepler.gl provides a handy set of utils to parse data from different format to the `data` object required in dataset. You rarely need to manually format the data obejct.
+Kepler.gl provides a handy set of utils to parse data from different formats to the `data` object required in dataset. You rarely need to manually format the data obejct.
Use `KeplerGlSchema.getConfigToSave` to generate a json blob of the currents instance config.
The config object value will always have higher precedence than the options properties.
@@ -353,7 +353,7 @@ to match the `info.id` of your dataset to the `dataId` in each `layer`, `filter`
**Parameters**
-- `data` **[Object][154]**
+- `data` **[Object][154]** **\*required**
- `data.datasets` **([Array][164]<[Object][154]> | [Object][154])** **\*required** datasets can be a dataset or an array of datasets
Each dataset object needs to have `info` and `data` property.
- `data.datasets.info` **[Object][154]** \-info of a dataset
@@ -363,7 +363,7 @@ to match the `info.id` of your dataset to the `dataId` in each `layer`, `filter`
- `data.datasets.data.fields` **[Array][164]<[Object][154]>** **\*required** Array of fields,
- `data.datasets.data.fields.name` **[string][152]** **\*required** Name of the field,
- `data.datasets.data.rows` **[Array][164]<[Array][164]>** **\*required** Array of rows, in a tabular format with `fields` and `rows`
- - `data.options` **[Object][154]**
+ - `data.options` **[Object][154]**
- `data.options.centerMap` **[boolean][155]** `default: true` if `centerMap` is set to `true` kepler.gl will
place the map view within the data points boundaries. `options.centerMap` will override `config.mapState` if passed in.
- `data.options.readOnly` **[boolean][155]** `default: false` if `readOnly` is set to `true`
@@ -432,7 +432,7 @@ Initialize kepler.gl reducer. It is used to pass in `mapboxApiAccessToken` to `m
**Parameters**
-- `payload` **[Object][154]**
+- `payload` **[Object][154]**
- `payload.mapboxApiAccessToken` **[string][152]** mapboxApiAccessToken to be saved to mapStyle reducer
- `payload.mapboxApiUrl` **[string][152]** mapboxApiUrl to be saved to mapStyle reducer.
- `payload.mapStylesReplaceDefault` **[Boolean][155]** mapStylesReplaceDefault to be saved to mapStyle reducer
@@ -497,7 +497,7 @@ Add a new filter
- `dataId` **[string][152]** dataset `id` this new filter is associated with
-Returns **{type: ActionTypes.ADD_FILTER, dataId: dataId}**
+Returns **{type: ActionTypes.ADD_FILTER, dataId: dataId}**
### addLayer
@@ -510,7 +510,7 @@ Add a new layer
- `props` **[Object][154]** new layer props
-Returns **{type: ActionTypes.ADD_LAYER, props: props}**
+Returns **{type: ActionTypes.ADD_LAYER, props: props}**
### enlargeFilter
@@ -523,7 +523,7 @@ Show larger time filter at bottom for time playback (apply to time filter only)
- `idx` **[Number][177]** index of filter to enlarge
-Returns **{type: ActionTypes.ENLARGE_FILTER, idx: idx}**
+Returns **{type: ActionTypes.ENLARGE_FILTER, idx: idx}**
### interactionConfigChange
@@ -536,7 +536,7 @@ Update `interactionConfig`
- `config` **[Object][154]** new config as key value map: `{tooltip: {enabled: true}}`
-Returns **{type: ActionTypes.INTERACTION_CONFIG_CHANGE, config: config}**
+Returns **{type: ActionTypes.INTERACTION_CONFIG_CHANGE, config: config}**
### layerConfigChange
@@ -550,7 +550,7 @@ Update layer base config: dataId, label, column, isVisible
- `oldLayer` **[Object][154]** layer to be updated
- `newConfig` **[Object][154]** new config
-Returns **{type: ActionTypes.LAYER_CONFIG_CHANGE, oldLayer: oldLayer, newConfig: newConfig}**
+Returns **{type: ActionTypes.LAYER_CONFIG_CHANGE, oldLayer: oldLayer, newConfig: newConfig}**
### layerTextLabelChange
@@ -578,7 +578,7 @@ Update layer type. Previews layer config will be copied if applicable.
- `oldLayer` **[Object][154]** layer to be updated
- `newType` **[string][152]** new type
-Returns **{type: ActionTypes.LAYER_TYPE_CHANGE, oldLayer: oldLayer, newType: newType}**
+Returns **{type: ActionTypes.LAYER_TYPE_CHANGE, oldLayer: oldLayer, newType: newType}**
### layerVisConfigChange
@@ -592,7 +592,7 @@ Update layer `visConfig`
- `oldLayer` **[Object][154]** layer to be updated
- `newVisConfig` **[Object][154]** new visConfig as a key value map: e.g. `{opacity: 0.8}`
-Returns **{type: ActionTypes.LAYER_VIS_CONFIG_CHANGE, oldLayer: oldLayer, newVisConfig: newVisConfig}**
+Returns **{type: ActionTypes.LAYER_VIS_CONFIG_CHANGE, oldLayer: oldLayer, newVisConfig: newVisConfig}**
### layerVisualChannelConfigChange
@@ -607,7 +607,7 @@ Update layer visual channel
- `newConfig` **[Object][154]** new visual channel config
- `channel` **[string][152]** channel to be updated
-Returns **{type: ActionTypes.LAYER_VISUAL_CHANNEL_CHANGE, oldLayer: oldLayer, newConfig: newConfig, channel: channel}**
+Returns **{type: ActionTypes.LAYER_VISUAL_CHANNEL_CHANGE, oldLayer: oldLayer, newConfig: newConfig, channel: channel}**
### loadFiles
@@ -620,7 +620,7 @@ Trigger file loading dispatch `addDataToMap` if succeed, or `loadFilesErr` if fa
- `files` **[Array][164]<[Object][154]>** array of fileblob
-Returns **{type: ActionTypes.LOAD_FILES, files: any}**
+Returns **{type: ActionTypes.LOAD_FILES, files: any}**
### loadFilesErr
@@ -631,9 +631,9 @@ Trigger loading file error
**Parameters**
-- `error` **any**
+- `error` **any**
-Returns **{type: ActionTypes.LOAD_FILES_ERR, error: any}**
+Returns **{type: ActionTypes.LOAD_FILES_ERR, error: any}**
### onLayerClick
@@ -646,7 +646,7 @@ Trigger layer click event with clicked object
- `info` **[Object][154]** Object clicked, returned by deck.gl
-Returns **{type: ActionTypes.LAYER_CLICK, info: info}**
+Returns **{type: ActionTypes.LAYER_CLICK, info: info}**
### onLayerHover
@@ -659,7 +659,7 @@ Trigger layer hover event with hovered object
- `info` **[Object][154]** Object hovered, returned by deck.gl
-Returns **{type: ActionTypes.LAYER_HOVER, info: info}**
+Returns **{type: ActionTypes.LAYER_HOVER, info: info}**
### onMapClick
@@ -668,7 +668,7 @@ Trigger map click event, unselect clicked object
- **ActionTypes**: [`ActionTypes.MAP_CLICK`][12]
- **Updaters**: [`visStateUpdaters.mapClickUpdater`][188]
-Returns **{type: ActionTypes.MAP_CLICK}**
+Returns **{type: ActionTypes.MAP_CLICK}**
### onMouseMove
@@ -683,7 +683,7 @@ React-map-gl PointerEvent
- `evt` **[Object][154]** PointerEvent
-Returns **{type: ActionTypes.MAP_CLICK}**
+Returns **{type: ActionTypes.MAP_CLICK}**
### removeDataset
@@ -696,7 +696,7 @@ Remove a dataset and all layers, filters, tooltip configs that based on it
- `key` **[string][152]** dataset id
-Returns **{type: ActionTypes.REMOVE_DATASET, key: key}**
+Returns **{type: ActionTypes.REMOVE_DATASET, key: key}**
### removeFilter
@@ -709,7 +709,7 @@ Remove a filter from `visState.filters`, once a filter is removed, data will be
- `idx` **[Number][177]** idx of filter to be removed
-Returns **{type: ActionTypes.REMOVE_FILTER, idx: idx}**
+Returns **{type: ActionTypes.REMOVE_FILTER, idx: idx}**
### removeLayer
@@ -722,7 +722,7 @@ Remove a layer
- `idx` **[Number][177]** idx of layer to be removed
-Returns **{type: ActionTypes.REMOVE_LAYER, idx: idx}**
+Returns **{type: ActionTypes.REMOVE_LAYER, idx: idx}**
### reorderLayer
@@ -743,7 +743,7 @@ Reorder layer, order is an array of layer indexes, index 0 will be the one at th
this.props.dispatch(reorderLayer([1, 0, 2, 3]));
```
-Returns **{type: ActionTypes.REORDER_LAYER, order: order}**
+Returns **{type: ActionTypes.REORDER_LAYER, order: order}**
### setFilter
@@ -758,7 +758,7 @@ Update filter property
- `prop` **[string][152]** `prop` of filter, e,g, `dataId`, `name`, `value`
- `value` **any** new value
-Returns **{type: ActionTypes.SET_FILTER, idx: idx, prop: prop, value: value}**
+Returns **{type: ActionTypes.SET_FILTER, idx: idx, prop: prop, value: value}**
### setFilterPlot
@@ -769,10 +769,10 @@ Set the property of a filter plot
**Parameters**
-- `idx` **[Number][177]**
+- `idx` **[Number][177]**
- `newProp` **[Object][154]** key value mapping of new prop `{yAxis: 'histogram'}`
-Returns **{type: ActionTypes.SET_FILTER_PLOT, idx: any, newProp: any}**
+Returns **{type: ActionTypes.SET_FILTER_PLOT, idx: any, newProp: any}**
### showDatasetTable
@@ -785,7 +785,7 @@ Display dataset table in a modal
- `dataId` **[string][152]** dataset id to show in table
-Returns **{type: ActionTypes.SHOW_DATASET_TABLE, dataId: dataId}**
+Returns **{type: ActionTypes.SHOW_DATASET_TABLE, dataId: dataId}**
### toggleAnimation
@@ -798,7 +798,7 @@ Start and end filter animation
- `idx` **[Number][177]** idx of filter
-Returns **{type: ActionTypes.TOGGLE_FILTER_ANIMATION, idx: idx}**
+Returns **{type: ActionTypes.TOGGLE_FILTER_ANIMATION, idx: idx}**
### toggleLayerForMap
@@ -812,7 +812,7 @@ Toggle visibility of a layer in a split map
- `mapIndex` **[Number][177]** index of the split map
- `layerId` **[string][152]** id of the layer
-Returns **{type: ActionTypes.TOGGLE_LAYER_FOR_MAP, mapIndex: any, layerId: any}**
+Returns **{type: ActionTypes.TOGGLE_LAYER_FOR_MAP, mapIndex: any, layerId: any}**
### updateAnimationSpeed
@@ -826,7 +826,7 @@ Change filter animation speed
- `idx` **[Number][177]** `idx` of filter
- `speed` **[Number][177]** `speed` to change it to. `speed` is a multiplier
-Returns **{type: ActionTypes.UPDATE_FILTER_ANIMATION_SPEED, idx: idx, speed: speed}**
+Returns **{type: ActionTypes.UPDATE_FILTER_ANIMATION_SPEED, idx: idx, speed: speed}**
### updateLayerBlending
@@ -839,7 +839,7 @@ Update layer blending mode
- `mode` **[string][152]** one of `additive`, `normal` and `subtractive`
-Returns **{type: ActionTypes.UPDATE_LAYER_BLENDING, mode: mode}**
+Returns **{type: ActionTypes.UPDATE_LAYER_BLENDING, mode: mode}**
### updateVisData
@@ -859,14 +859,14 @@ Add new dataset to `visState`, with option to load a map config along with the d
- `datasets.data.fields` **[Array][164]<[Object][154]>** **\*required** Array of fields,
- `datasets.data.fields.name` **[string][152]** **\*required** Name of the field,
- `datasets.data.rows` **[Array][164]<[Array][164]>** **\*required** Array of rows, in a tabular format with `fields` and `rows`
-- `options` **[Object][154]**
+- `options` **[Object][154]**
- `options.centerMap` **[boolean][155]** `default: true` if `centerMap` is set to `true` kepler.gl will
place the map view within the data points boundaries
- `options.readOnly` **[boolean][155]** `default: false` if `readOnly` is set to `true`
the left setting panel will be hidden
- `config` **[Object][154]** this object will contain the full kepler.gl instance configuration {mapState, mapStyle, visState}
-Returns **{type: ActionTypes.UPDATE_VIS_DATA, datasets: datasets, options: options, config: config}**
+Returns **{type: ActionTypes.UPDATE_VIS_DATA, datasets: datasets, options: options, config: config}**
## uiStateActions
@@ -1084,7 +1084,7 @@ If `mint` is set to be `true` in the component prop, the instance state will be
the instance state and later transfer it to a newly mounted component with the same `id`
- **ActionTypes**: [`ActionTypes.DELETE_ENTRY`][12]
-- **Updaters**:
+- **Updaters**:
**Parameters**
@@ -1097,11 +1097,11 @@ Note that if you dispatch actions such as adding data to a kepler.gl instance be
performed. Instance reducer can only handle actions when it is instantiated.
- **ActionTypes**: [`ActionTypes.REGISTER_ENTRY`][12]
-- **Updaters**:
+- **Updaters**:
**Parameters**
-- `payload` **[Object][154]**
+- `payload` **[Object][154]**
- `payload.id` **[string][152]** **\*required** The id of the instance
- `payload.mint` **[boolean][155]** Whether to use a fresh empty state, when `mint: true` it will _always_ load a fresh state when the component is re-mounted.
When `mint: false` it will register with existing instance state under the same `id`, when the component is unmounted then mounted again. Default: `true`
@@ -1114,7 +1114,7 @@ performed. Instance reducer can only handle actions when it is instantiated.
Rename an instance in the root reducer, keep its entire state
- **ActionTypes**: [`ActionTypes.RENAME_ENTRY`][12]
-- **Updaters**:
+- **Updaters**:
**Parameters**
@@ -1544,7 +1544,7 @@ Set the expor tmap format (html, json)
[165]: ../reducers/map-style.md#mapstyleupdatersset3dbuildingcolorupdater
-[166]: ../reducers/composers.md#combinedupdatersadddatatomapupdater
+[166]: ../reducers/combine.md#combinedupdatersadddatatomapupdater
[167]: ../reducers/map-style.md#mapstyleupdatersinitmapstyleupdater
diff --git a/docs/api-reference/get-started.md b/docs/api-reference/get-started.md
index 0e5b60303..60c176d12 100644
--- a/docs/api-reference/get-started.md
+++ b/docs/api-reference/get-started.md
@@ -55,7 +55,7 @@ const Map = props => (
#### 3. Add data to map
-In order to interact with a kepler.gl instance and add new data to it, you can dispatch __`addDataToMap`__ action from anywhere inside your app. It adds dataset to kepler.gl instance and update the full configuration (mapState, mapStyle, visState).
+In order to interact with a kepler.gl instance and add new data to it, you can dispatch the __`addDataToMap`__ action from anywhere inside your app. It adds dataset(s) to a kepler.gl instance and updates the full configuration (mapState, mapStyle, visState).
Read more about [addDataToMap](./actions/actions.md#adddatatomap)