arcgis-layer-list-next | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-layer-list-next";

Inheritance: ArcgisLayerListNext→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.1

beta

The Layer List (next) component is the successor to the Layer List component, provided to you early for testing and feedback. In version 6.0, the implementation of arcgis-layer-list will be updated under the hood to that of arcgis-layer-list-next, and this component will be removed. There is a breaking change in how events for catalogLayerList and tableList are handled compared to Layer List. To update at version 6.0, simply remove -next from the component name.

The Layer List (next) provides a way to display a list of layers and switch on/off their visibility. The listItemCreatedFunction and the ListItem API provides access to each layer's properties, allows the developer to configure actions related to the layer, and allows the developer to add content to the item related to the layer.

Notes

The Layer List does not emit an event when the visibility of a layer changes. To respond to layer visibility changes, watch the visible property of layers in the allLayers property with reactiveUtils.

To hide layers in the map from the Layer List, you must set the listMode property on the desired layers to hide.

When a KnowledgeGraphLayer is present in the map, the Layer List will display the tables as a tableList ListItem.

When a CatalogLayer is present in the map, the Layer List will display the dynamicGroupLayer in a catalogLayerList ListItem.

Keyboard Navigation

The Layer List supports keyboard navigation using the Treegrid Pattern for improved accessibility. Refer to the Calcite List component documentation for detailed keyboard interaction guidelines: Calcite List Keyboard Navigation.

Demo

Properties

Property	Attribute	Type
autoDestroyDisabled	auto-destroy-disabled	boolean
catalogLayerList readonly		ArcgisCatalogLayerList \| undefined
catalogOptions		CatalogLayerListParams \| undefined
closed	closed	boolean
collapsed	collapsed	boolean
dragEnabled	drag-enabled	boolean
filterPlaceholder	filter-placeholder	string
filterPredicate		((item: ListItem \| TableListListItem) => boolean) \| undefined
filterText	filter-text	string
headingLevel	heading-level	HeadingLevel
hideCatalogLayerList	hide-catalog-layer-list	boolean
hideStatusIndicators	hide-status-indicators	boolean
icon	icon	IconName
knowledgeGraphOptions		TableListParams \| undefined
label	label	string \| undefined
listItemCreatedFunction		ListItemModifier \| null \| undefined
minDragEnabledItems	min-drag-enabled-items	number
minFilterItems	min-filter-items	number
openedLayers readonly		Collection<FlowLayer>
operationalItems readonly		Collection<ListItem>
referenceElement	reference-element	ArcgisReferenceElement \| string \| undefined
selectedItems		Collection<ListItem>
selectionMode	selection-mode	List["selectionMode"]
showCloseButton	show-close-button	boolean
showCollapseButton	show-collapse-button	boolean
showErrors	show-errors	boolean
showFilter	show-filter	boolean
showHeading	show-heading	boolean
showTemporaryLayerIndicators	show-temporary-layer-indicators	boolean
state readonly		State
tableList readonly		ArcgisTableList \| undefined
view		MapViewOrSceneView \| null \| undefined
visibilityAppearance	visibility-appearance	VisibilityAppearance

autoDestroyDisabled

Property

Type: boolean

If true, the component will not be destroyed automatically when it is disconnected from the document. This is useful when you want to move the component to a different place on the page, or temporarily hide it. If this is set, make sure to call the destroy() method when you are done to prevent memory leaks.

Attribute: auto-destroy-disabled
Default value: false

catalogLayerList

readonly Property

Type: ArcgisCatalogLayerList | undefined

The CatalogLayerList that displays a catalog layer's dynamic group layer. The catalog layer list will be displayed as an expandable ListItem in the root of the layer list when a CatalogLayer is present in the map. This property is set when a catalog layer's dynamic group layer is expanded in the LayerList. Otherwise, it is null. This property is useful for listening to the arcgisTriggerAction event and managing selections in catalog layers.

CatalogLayerList

Example

// Use reactiveUtils to respond to the layerListElement.catalogLayerList "arcgisTriggerAction" event
const catalogLayerListActionHandle = reactiveUtils.on(
  () => layerListElement.catalogLayerList,
  "arcgisTriggerAction",
  async (event) => {
    const { action, item } = event.detail;
    if (action.id === "add-layer") {
      try {
        const parentCatalogLayer = getCatalogLayerForLayer(item.layer);
        if (!parentCatalogLayer) {
          return;
        }
        await addLayerFromDynamicGroup(item.layer);
        alert(`Added ${item.layer.title} to the map`);
      } catch (error) {
        console.error("Failed to add layer from dynamic group", error);
        alert(`Unable to add ${item.layer.title} to the map`);
      }
      layerListElement?.openedLayers?.pop();
    }
  },
);
layerListHandles.push(catalogLayerListActionHandle);

// Use reactiveUtils to watch for a selected item in the layerListElement.catalogLayerList
const catalogSelectionWatchHandle = reactiveUtils.watch(
  () =>
    layerListElement.catalogLayerList?.selectedItems?.at(0)?.layer as Layer,
  (layer) => {
    layer && handleLayerSelection(layer);
  },
);
layerListHandles.push(catalogSelectionWatchHandle);

catalogOptions

Property

Type: CatalogLayerListParams | undefined

CatalogLayer specific properties. Catalog layers will display their CatalogLayer#dynamicGroupLayer as an expandable arcgis-catalog-layer-list in the Layer List component. This list item will only be displayed when catalog layers with dynamic group layers are loaded in the map. These are the properties that are used to configure the arcgis-catalog-layer-list.

See also

arcgis-catalog-layer-list for more details on the catalog layer list and its properties.

Example

layerListElement.catalogOptions = {
    listItemCreatedFunction: (event) => {
      const { item } = event;
      item.actionsSections = [
        [
          {
            title: "Add layer to map",
            icon: "add-layer",
            id: "add-layer"
          }
        ]
      ];
    },
    selectionMode: "single"
  };

closed

Property

Type: boolean

Indicates whether a component is closed. When true, the component will be hidden.

Attribute: closed
Default value: false

collapsed

Property

Type: boolean

Indicates whether the component is collapsed. When collapsed, only the collapse button and heading are displayed.

See also

showCollapseButton

Attribute: collapsed
Default value: false

Example

layerListElement.collapsed = true;

dragEnabled

Property

Type: boolean

Indicates whether list items may be reordered within the list by dragging and dropping. MapImageLayer MapImageLayer#sublayers can be reordered only within their parent MapImageLayer and can not be dragged out as a separate layer. Drag won't be enabled until the number of list items is equal to or greater than than the value set set in minDragEnabledItems.

See also

minDragEnabledItems

Attribute: drag-enabled
Default value: false

Example

layerListElement.dragEnabled = true;

filterPlaceholder

Property

Type: string

Placeholder text used in the filter input if showFilter is true.

See also

showFilter

Attribute: filter-placeholder
Default value: ""

Example

layerListElement.filterPlaceholder = "Filter layers";

filterPredicate

Property

Type: ((item: ListItem | TableListListItem) => boolean) | undefined

Specifies a function to handle filtering list items.

Example

layerListElement.filterPredicate = (item) => item.title.toLowerCase().includes("streets");

filterText

Property

Type: string

The value of the filter input if showFilter is true.

See also

showFilter

Attribute: filter-text
Default value: ""

Example

reactiveUtils.watch(
  () => layerListElement.filterText,
  (filterText) => console.log(filterText)
);

headingLevel

Property

Type: HeadingLevel

Indicates the heading level to use for the heading of the component. By default, the heading is rendered as a level 2 heading (e.g., <h2>Layer List</h2>). Depending on the component's placement in your app, you may need to adjust this heading for proper semantics. This is important for meeting accessibility standards.

See also

showHeading

Attribute: heading-level
Default value: 2

Example

layerListElement.headingLevel = 3;

hideCatalogLayerList

Property

Type: boolean

This property provides the ability to show or hide the catalog layer list.

Attribute: hide-catalog-layer-list
Default value: false

hideStatusIndicators

Property

Type: boolean

This property provides the ability to show or hide status indicators.

Attribute: hide-status-indicators
Default value: false

icon

Property

Type: IconName

Icon which represents the component. Typically used when the component is controlled by another component (e.g. by the Expand component).

See also

Calcite Icons

Attribute: icon
Default value: "layers"

knowledgeGraphOptions

Property

Type: TableListParams | undefined

KnowledgeGraphLayer specific properties. KnowledgeGraphLayer#tables as an expandable arcgis-table-list in the Layer List component and can be accessed with the tableList property. This tables list item will only be displayed when knowledge graph layers with tables are loaded in the map. These are the properties that are used to configure the arcgis-table-list.

See also

arcgis-table-list for more details on the table list and its properties.

Example

layerListElement.knowledgeGraphOptions = {
  filterPlaceholder: "Filter tables",
  listItemCreatedFunction: (event) => {
    const { item } = event;
    item.actionsSections = [
      [
        {
          icon: "table",
          id: "open-table",
          title: "Show table"
        },
        {
          icon: "information",
          id: "information",
          title: "Show information"
        }
      ]
    ];
  },
  minFilterItems: 1
}

label

Property

Type: string | undefined

The component's default label.

Attribute: label

listItemCreatedFunction

Property

Type: ListItemModifier | null | undefined

A function that executes each time a ListItem is created. Use this function to add actions and panels to list items, and to override the default settings of a list item. Actions can be added to list items using the ListItem#actionsSections property.

See also

Sample - LayerList component with actions

Example

layerListElement.listItemCreatedFunction = async function (event) {
  // The event object contains an item property.
  // It is a ListItem referencing the associated layer
  // and other properties. You can control the visibility of the
  // item, its title, and actions using this object.
  const item = event.item;

  await item.layer.when();

  if (item.title === "US Demographics") {
    // An array of objects defining actions to place in the LayerList.
    // By making this array two-dimensional, you can separate similar
    // actions into separate groups with a breaking line.
    item.actionsSections = [
      [
        {
          title: "Go to full extent",
          icon: "zoom-out-fixed",
          id: "full-extent",
        },
        {
          title: "Layer information",
          icon: "information",
          id: "information",
        },
      ],
      [
        {
          title: "Increase opacity",
          icon: "chevron-up",
          id: "increase-opacity",
        },
        {
          title: "Decrease opacity",
          icon: "chevron-down",
          id: "decrease-opacity",
        },
      ],
    ];
  }
}

minDragEnabledItems

Property

Type: number

The minimum number of list items required to enable drag and drop reordering with dragEnabled.

See also

dragEnabled

Attribute: min-drag-enabled-items
Default value: 2

Example

layerListElement.dragEnabled = true;
layerListElement.minDragEnabledItems = 5;

minFilterItems

Property

Type: number

The minimum number of list items required to display the showFilter input box.

See also

showFilter

Attribute: min-filter-items
Default value: 10

Example

layerListElement.showFilter = true;
layerListElement.minFilterItems = 5;

openedLayers

readonly Property

Type: Collection<FlowLayer>

A collection of Layers that are opened in a catalogLayerList or tableList flow item. This property is useful for backing out of the catalog layer list or table list programmatically to the parent layer list.

See also

Default value: []

Example

// back out of the catalog layer list to the main layer list
layerListElement.openedLayers.pop();

operationalItems

readonly Property

Type: Collection<ListItem>

A collection of ListItems representing the operational layers in the layer list.

referenceElement

Property

Type: ArcgisReferenceElement | string | undefined

By assigning the id attribute of the Map or Scene component to this property, you can position a child component anywhere in the DOM while still maintaining a connection to the Map or Scene.

See also

Associate components with a Map or Scene component

Attribute: reference-element

selectedItems

Property

Type: Collection<ListItem>

A collection of selected ListItems representing operational layers selected by the user in the layer list.

See also

selectionMode

selectionMode

Property

Type: List["selectionMode"]

Specifies the selection mode. Selected items are available in the selectedItems property.

Value	Description
multiple	Allows any number of items to be selected at once. This is useful when you want to apply an operation to multiple items at the same time.
none	Disables selection. Use this when you want to prevent selecting items.
single	Allows only one item to be selected at a time. If another item is selected, the previous selection is cleared. This is useful when you want to ensure that a maximum of one item is selected at a time.
single-persist	Allows only one item to be selected at a time and prevents de-selection. Once an item is selected, it remains selected until another item is selected. This is useful when you want to ensure that there is always exactly one selected item.

See also

selectedItems

Attribute: selection-mode
Default value: "none"

Example

layerListElement.selectionMode = "multiple";

showCloseButton

Property

Type: boolean

This property provides the ability to show or hide the close button.

Attribute: show-close-button
Default value: false

showCollapseButton

Property

Type: boolean

This property provides the ability to show or hide the collapse button.

Attribute: show-collapse-button
Default value: false

showErrors

Property

Type: boolean

This property provides the ability to show or hide error indicators.

Attribute: show-errors
Default value: false

showFilter

Property

Type: boolean

This property provides the ability to show or hide the filter input.

Attribute: show-filter
Default value: false

showHeading

Property

Type: boolean

This property provides the ability to show or hide the heading.

Attribute: show-heading
Default value: false

showTemporaryLayerIndicators

Property

Type: boolean

This property provides the ability to show or hide temporary layer indicators.

Attribute: show-temporary-layer-indicators
Default value: false

state

readonly Property

Type: State

The current state of the component.

Default value: "disabled"

tableList

readonly Property

Type: ArcgisTableList | undefined

The arcgis-table-list component instance that displays the tables associated with a KnowledgeGraphLayer. The table list will be displayed as an expandable list item. This property is set when a knowledge graph layer's tables list item is expanded in the LayerList. Otherwise, it is null. This list item will only be displayed when knowledge graph layers with tables are loaded in the map and will be displayed as a child of the knowledge graph layer. This property is useful for listening to the arcgisTriggerAction event and managing selections in knowledge graph tables.

tableList

See also

knowledgeGraphOptions for configuring the table list and its items.

Example

// Use reactiveUtils to respond to the layerListElement.tableList "arcgisTriggerAction" event
const tableListActionHandle = reactiveUtils.on(
  () => layerListElement.tableList,
  "arcgisTriggerAction",
  (event: any) => {
    const { action, item } = event.detail;
    if (action.id === "information") {
      alert(`${item.layer?.title}`);
    }
  },
);
layerListHandles.push(tableListActionHandle);

// Use reactiveUtils to watch for a selected item in the layerListElement.tableList
const tableSelectionWatchHandle = reactiveUtils.watch(
  () => layerListElement.tableList?.selectedItems?.at(0)?.layer,
  (layer) => {
    layer && handleLayerSelection(layer);
  },
);
layerListHandles.push(tableSelectionWatchHandle);

view

Property

Type: MapViewOrSceneView | null | undefined

The view associated with the component.

Note: The recommended approach is to fully migrate applications to use map and scene components and avoid using MapView and SceneView directly. However, if you are migrating a large application from widgets to components, you might prefer a more gradual transition. To support this use case, the SDK includes this view property which connects a component to a MapView or SceneView. Ultimately, once migration is complete, the arcgis-layer-list-next component will be associated with a map or scene component rather than using the view property.

visibilityAppearance

Property

Type: VisibilityAppearance

Determines the icons used to indicate visibility.

Value	Description	Example
default	Displays view icons on the far side. Icons are hidden except on hover or if they have keyboard focus. See view-visible and view-hide calcite icons.
checkbox	Displays checkbox icons on the near side. See check-square-f and square calcite icons.

Attribute: visibility-appearance
Default value: "default"

Example

layerListElement.visibilityAppearance = "checkbox";

Methods

Method	Signature
componentOnReady inherited	componentOnReady(): Promise<this>
destroy	destroy(): Promise<void>

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Inherited from: this

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisLayerListNext = document.createElement("arcgis-layer-list-next");
document.body.append(arcgisLayerListNext);
await arcgisLayerListNext.componentOnReady();
console.log("arcgis-layer-list-next is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

Events

Name	Type
arcgisClose	CustomEvent<void>
arcgisPropertyChange	CustomEvent<{ name: "state"; }>
arcgisReady	CustomEvent<void>
arcgisTriggerAction	CustomEvent<LayerListViewModelEvents["trigger-action"]>

arcgisClose

Event

arcgisClose: CustomEvent<void>

Emitted when the component's close button is clicked.

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "state"; }>

Emitted when the value of a property is changed. Use this to listen to changes to properties.

arcgisReady

Event

arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready to be interacted with.

arcgisTriggerAction

Event

arcgisTriggerAction: CustomEvent<LayerListViewModelEvents["trigger-action"]>

Emitted when an action is triggered on the component.