Introducing Elements: a library for rapidly building Mapbox-based web applications
In December of last year, we quietly open-sourced a library we call Elements. Elements is a set of reusable and themeable React components for rapidly building user interfaces for web mapping applications. Today we release version 1.2.0, so we decided it would be a good idea to dive into some details about the project.
Motivation
Similar to paper maps, digital maps generally include a common set of elements – things like zoom controls, basemap options, and a layer list. A set of reusable and themeable components enables developers to rapidly build map-based applications that match existing brands and frees up their time to focus more on the specific business logic of their applications.
This idea has been realized to a degree in tools like Esri’s Web AppBuilder – a platform that lets non-developers to configure “widgets” for mapping applications. Elements are similar in concept to these “widgets”; however, they are different in that:
a) They are primarily meant for developers, and
b) Unlike Esri’s widgets, which can only be used in specific application templates, Elements will work in any React-based web application
Elements currently works with MapboxGL.js. We chose Mapbox because:
a) It’s what we use most often at CartoLab in our daily work.
b) Compared to other mapping libraries, it has the fewest UI elements or plugins available.
Comparison to other React mapping projects
Elements is different from libraries like react-map-gl and react-mapbox-gl in that it is not an attempt to port the MapboxGL API into React Components. Instead, it is our philosophy that MapboxGL should manage the map and its WebGL Context, while React simply manages all the other UI elements in an application that need to interact with a map. Working with Elements, you should be able to use MapboxGL.js directly or use one of these wrapper libraries (as long as you can pass in the map instance to Elements' Context).
Features
Elements currently includes 14 React components:
Add Data: Adds a form for letting users add local data or data from a URL to the map.
Basemap Switcher: Allows the user to switch between various Mapbox styles.
Bookmarks: Allows the user to save a map extent and quickly return to it later.
Draw: Draw shapes and text on the map
Home: Establishes initial coordinates for the map and returns to that extent when clicked
Layer List: Includes an operational layer list to toggle visibility of layers on the map. Also includes legend symbols.
Map: Very basic wrapper around a MapboxGL map that writes map info to a context that can be shared with other components.
Map Info: Displays information about the current map extent, zoom level, and cursor coordinates
Popup: Displays feature attribute information in a popup on the map when the feature is clicked.
Measure: Lets users make distance and area measurements by drawing on the map.
Scale Bar: Displays a scale bar for the map.
Search: Allows the user to enter an address, get suggestions, and then zoom to the chosen address on the map. Uses Mapbox’s geocoding API.
Select: Enables users to interactively select features on the map
Zoom: Zoom controls
Basic Example
In the entry point/top level of your application, enable Elements by importing and wrapping the app in the <ElementsProvider>. The Elements Provider does two things:
a) It passes in theme information. See Theming section for more details. b) It creates a shared map context so that the state of the map can be read and controlled by the components.
Example in the index.js file of an app created with Create React App:
Example App.js file: Note how you can place CartoLab Elements as children or siblings of the Map component. Your choice may depend on how you want to position these components in your application. You can see more examples of usage in the source for our Storybook app and in the tests.
Theming
Application theming is a first-class concern for the Elements library. To that end, we chose to build the library with ThemeUI, which uses Styled System and the System UI Theme Specification. This means that you can use any theme made for Styled System, Theme-UI, Rebass, or any other compliant theme with CartoLab Elements.
We've provided a default theme to help you get started quickly.
Storybook Examples and Playground
You can explore Elements in our interactive playground, built with Storybook. We'll be adding code snippets and other docs to the Storybook very soon!
Image from the Elements Storybook site, showing the LayerList componen
In the coming weeks and months, we'll be adding tutorials for how to build some actual applications with Elements. Stay tuned!
