July 2017 · Esri · design

LayerList Widget

ArcGIS API for JavaScript

The LayerList widget is the primary way in the JavaScript API to display a hierarchical list of layers and layer actions in web applications.

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):

Legacy LayerList widget in the map viewer

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 needed to allow quick access to common actions from what could become a very long list. I quickly learned that the distinction between widget-level actions and app-level actions was critical, because it would shape the information architecture of many apps built by developers.

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 is possible for the LayerList to contain only one layer, such as a basemap.

Minimum-height LayerList layout with a single basemap layer

Layer actions include one quick action beside the layer title, plus an overflow actions panel.

LayerList actions with a quick action and overflow menu

The LayerList can contain hierarchical layers, and showing visibility across levels is tricky. Through research and testing, I designed a pattern where a parent layer is considered visible as long as at least one sublayer is visible. This removed the need for a mixed state on the parent layer and made the logic easier for end users to understand.

Full LayerList with hierarchical layers and visibility controls

Release

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