LayerList Widget

ArcGIS API for JavaScript

Background

The ArcGIS API for JavaScript allows developers to work with maps and layers in Esri’s ArcGIS ecosystem and helps developers build web mapping user experiences. The LayerList widget is the primary way in the API to display a hierarchical list of layers and related actions.

Problems to solve

This is the legacy LayerList widget design (highlighted in red outline):

The legacy design had a few problems:

The visibility status of layers is indicated by checkboxes, but the checkbox behavior is confusing—the parent layer is checked when its child layers are not checked.
Actions on layers are available only on hover.

Design research

I examined the user experience of layer lists in both GIS and non-GIS applications (MapBox, ArcGIS Pro, ArcGIS Earth, Photoshop, Sketch, etc). The LayerList needs to allow quick access to common actions from a potentially long list of actions. I quickly learned that the distinction of actions at the widget and app levels is critical, which would ultimately determine the information architecture of apps that many developers will build.

Through interviews with experts, app developers, and end users, I developed two design principles for whether the LayerList Widget should perform an action or not:

The LayerList widget should perform actions to its layers (i.e., layers as targets of actions).
The LayerList widget should not perform actions with its layers (i.e., layers as inputs of actions)

The table below shows samples of actions at the LayerList widget level and app level.

Actions of the LayerList widget	Actions controlled at the app level
Enable a layer’s popup Set a layer’s opacity Change a layer’s symbology Filter a layer’s features	Aggregate points using a layer Find locations by referencing a layer Merge a layer with another layer

Design

The LayerList widget needs to be flexible enough for developers to configure it in a wide range of use cases.

It's possible that the LayerList has only one layer (as base map).

Layer actions include one quick action next to layer title and overflow actions panel.

The LayerList could have hierarchical layers. Show the visibility of layers at different levels is tricky. Through research and testing, I designed this pattern: a parent layer’s visibility is ON as long as at least one sublayer is visible. This eliminated the need to show a mixed visibility state for the parent layer and made it easy for end users to understand the logic.

Release

The LayerList widget has been released in ArcGIS API for JavaScript since Version 4.2.