Tools for building Redux applications with Mapbox GL JS
Add middleware to your Redux store and a control to your Mapbox GL JS map to sync your application state with the map's internally managed state, while maintaining clean one-way data-flow.
ReduxMapControl
: Add this to the Mapbox GL JS map. It subscribes to map events and dispatches corresponding Redux actions.mapMiddleware
: Add this to the Redux store. WhenMapActionCreators
are used, mapMiddleware will translate those actions into method invocations on the map.MapActionCreators
: Use these to programmatically change the map's state.bindMapActionCreators
: Returns a set ofMapActionCreators
scoped to a specific map.MapActionTypes
: Use these in your reducer to identify actions triggered by map events.
Let's say you have a button to zoom out and a display of the map's zoom level. When you click the zoom out button, the data flow will look like this:
- A click handler invokes
MapActionCreators.zoomOut()
to create a zoomOut action. mapMiddleware
detects the zoomOut action and tells the map to zoom out.- While the map zooms, it fires 'zoom' events that
ReduxMapControl
converts to actions. - Your reducer hears of these 'zoom' actions and updates the displayed zoom level accordingly.
So: UI -> click -> action -> map -> map event -> action -> reducer -> UI
The MapActionCreators
correspond to Mapbox GL JS methods, with a few special
cases. You can use them with the same function signature documented for the GL
JS methods.
The MapActionTypes
correspond to Mapbox GL JS events, with a few special
cases. Actions of these types will include the following properties:
map
: Use this to gather information about the map, e.g. onMapActionTypes.zoom
. You probably want to update your zoom state with the value frommap.getZoom()
.mapId
: You'll want to ignore the action if it doesn't pertain to your map.event
: The Mapbox GL JS map event type.eventData
: The Mapbox GL JS map event data.type
: The action type.
If you add a new map action creator or type, please also update the relevant tests and this README.
These action creators correspond directly with Mapbox GL JS methods:
setCenter
panBy
panTo
setZoom
zoomTo
zoomOut
zoomIn
setBearing
rotateTo
resetNorth
snapToNorth
setPitch
fitBounds
jumpTo
flyTo
easeTo
stop
setProjection
There are a few special action creators that do not directly correspond to Mapbox GL JS map methods.
Dispatch a MapActionCreators.sync(
) action at any time to give your reducer
an opportunity to sync up with map state.
When the middleware detects this action it dispatches a MapActionTypes.sync
action that you can use in your reducer.
Dispatch MapActionCreators.setShowCollisionBoxes(true)
to turn on collision
boxes, or MapActionCreators.setShowCollisionBoxes(false)
to turn them off.
After the middleware has adjusted the map's setting, it dispatches a
MapActionTypes.setShowCollisionBoxes
action that you can use in your reducer.
Dispatch MapActionCreators.setShowTileBoundaries(true)
to turn on collision
boxes, or MapActionCreators.setShowTileBoundaries(false)
to turn them off.
After the middleware has adjusted the map's setting, it dispatches a
MapActionTypes.setShowTileBoundaries
action that you can use in your reducer.
These action types correspond directly with Mapbox GL JS events:
move
movestart
moveend
zoom
zoomstart
zoomend
rotate
rotatestart
rotateend
pitch
load
These ones correspond with the special action creators described above:
sync
setShowTileBoundaries
setShowCollisionBoxes
First, create a CHANGELOG entry for your release. Commit the entry followed by these commands:
npm version {major|minor|patch}
git push
git push --tags
mbx npm publish