Elements v2 Released!

Earlier this month we released version 2 of @cartolab/elements - our open source library that contains themable React components for rapid development UIs for map-based applications. Work on this version began in late 2020 with the full intention to release it in 2021, but some other priorities pushed it to the back burner for a while. However, we’ve been testing the beta versions of v2 for almost a year in several applications now, and are finally ready to share it. Better late than never, right?

Refresher on Elements

As I mentioned, Elements is a React component library that includes 14 components to help make developing UIs for mapping applications a faster process. Elements is compatible with the MapboxGL web mapping library. Its primary concern is with providing a consistent interface and simple theming options for elements that are commonly found in interactive maps. These options include everything from zoom controls and scale bars to forms for adding data files on top of a map.

The library is fully open source, lightweight, and can be demoed on our Storybook site.

If you’re looking for a deep dive into some of the motivations and development decisions behind Elements, check out the talk I gave about it during a webinar hosted by Mapbox.

What’s New in v2?

Features

One of the most significant updates to the library is changes in the BaseComponent that is used in all of the components. We added a new baseType property that enables all of the Elements components to be displayed in a styled, closable Panel, as a configurable Button (a new feature we left up to application developers to implement in v1), or with no container at all so they can easily be integrated with existing UI layouts. For the button types, there is an additional buttonOptions property that can be used for further configuration.

Some parts of the BaseComponent API were removed. For example, we removed the positioning props `top`, `left`, etc. Instead, we have now ensured that the sx styling prop is passed down in the same manner across all components. Developers can now pass positioning information this way with a consistent experience.

The changes to BaseComponent are breaking, meaning that existing applications that use v1 will need to make a few changes to the props that are currently passed to their components. In our experience, the switch takes less than a day.

We have added top-level Context values that allow sharing of information from the Elements library to applications that use it. These new values are drawMode and selectMode, which can be used to send apps information about which tools are currently active.

Popups now support multiple features in a single popup, with navigation buttons to move between pages. This can be useful when a map has overlapping features. 

Finally, we have added a preserveLayers property to the BasemapSwitcher component that supports keeping an overlay layers on the map when switching basemaps. This is a long-known issue with MapboxGL, and we are pleased to have the start of a solution to this problem.

Fixes

• We fixed an issue in the Legend component so that layers with data-driven values will display the legend properly when there are 2 or more value breaks. Previously this only occurred when there were 3 or more. This fix was also merged back into v1 with the release of 1.3.8.

• We fixed an issue with non-responsive popups when a new map loads.

Housekeeping

We made updates to the following major dependencies and peer dependencies for Elements:

• Added compatibility with React 17. Elements is compatible with React versions 16.8.6+ and 17.0.2+

• Added compatibility with MapboxGL v2. Elements works with versions 1.5.0+ and 2.0.0+

• Upgraded ThemeUI to v 0.12.0

• Updated packaging to use Node 16, Yarn 3, and Rollup 2.

All in all, our housekeeping work drastically reduced the bundle size for the production version of Elements! Bundlephobia now shows a minified size of 5kb, with a g-zipped size of 1.5kb - almost a 5x size reduction from version 1! The library is tree-shakable so, on top of the small bundle size, your app will only import the pieces of Elements you need!

We are looking forward to active development on Elements throughout this coming year! If you have any questions about Elements, be sure to drop us a line via our Contact Form or on Twitter!