▾
import "@arcgis/map-components/components/arcgis-layer-list-next";- Inheritance
- ArcgisLayerListNext→
HTMLElement
- Since
- ArcGIS Maps SDK for JavaScript 5.1
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 the name of the events for catalogLayerList and
tableList compared to arcgis-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 Item API provide access to each layer's properties, allow the developer to configure actions related to the layer, and allow the developer to add content to the item related to the layer. Track info items can also be configured with custom panel content. Legend panel content is not supported for individual track info parts.
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 |
|---|---|---|
| auto-destroy-disabled | ||
| readonly | | |
| | ||
| closed | ||
| collapsed | ||
| drag-enabled | ||
| filter-placeholder | ||
| | ||
| filter-text | ||
| heading-level | ||
| hide-catalog-layer-list | ||
| hide-no-filter-results-notice | ||
| hide-no-items-notice | ||
| hide-status-indicators | ||
| icon | ||
| | ||
| label | ||
| | ||
| list-mode-disabled | ||
| | ||
| min-drag-enabled-items | ||
| min-filter-items | ||
| readonly | | |
| readonly | | |
| reference-element | ||
| | ||
| selection-mode | List["selectionMode"] | |
| show-close-button | ||
| show-collapse-button | ||
| show-errors | ||
| show-filter | ||
| show-heading | ||
| show-temporary-layer-indicators | ||
| readonly | | |
| readonly | | |
| | ||
| visibility-appearance |
autoDestroyDisabled
- 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
- Example
- <arcgis-layer-list-next auto-destroy-disabled></arcgis-layer-list-next>layerListNextElement.autoDestroyDisabled = true;
catalogLayerList
The arcgis-catalog-layer-list-next that displays a catalog layer's dynamic group layer.
The catalog layer list will be displayed as an expandable Item 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 layer list. Otherwise, it is null.
This property is useful for listening to the arcgis-catalog-layer-list-next.@arcgisTriggerAction event and managing selections in catalog layers.
- Example
- // Use reactiveUtils to respond to the layerListElement.catalogLayerList "arcgisTriggerAction" eventconst 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.catalogLayerListconst catalogSelectionWatchHandle = reactiveUtils.watch(() =>layerListElement.catalogLayerList?.selectedItems?.at(0)?.layer,(layer) => {layer && handleLayerSelection(layer);},);layerListHandles.push(catalogSelectionWatchHandle);
catalogOptions
- Type
- CatalogLayerListParams | undefined
CatalogLayer specific properties. Catalog layers will display their CatalogLayer#dynamicGroupLayer as an expandable arcgis-catalog-layer-list-next in the arcgis-layer-list-next 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-next.
- Example
- layerListElement.catalogOptions = {listItemCreatedFunction: (event) => {const { item } = event;item.actionsSections = [[new ActionToggle({title: "Add layer to map",icon: "add-layer",id: "add-layer"})]];},selectionMode: "single"};
closed
- Type
- boolean
Indicates whether a component is closed. When true, the component will be hidden.
- Attribute
- closed
- Default value
- false
- Example
- <arcgis-layer-list-next closed></arcgis-layer-list-next>layerListNextElement.closed = true;
collapsed
- Type
- boolean
Indicates whether the component is collapsed. When collapsed, only the collapse button and heading are displayed.
- Attribute
- collapsed
- Default value
- false
- Example
- <arcgis-layer-list-next collapsed></arcgis-layer-list-next>layerListNextElement.collapsed = true;
dragEnabled
- Type
- boolean
Indicates whether 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 and drop won't be enabled until the number of list items is equal to or greater than than the value set set in minDragEnabledItems.
- Attribute
- drag-enabled
- Default value
- false
- Example
- <arcgis-layer-list-next drag-enabled></arcgis-layer-list-next>layerListNextElement.dragEnabled = true;
filterPlaceholder
- Type
- string
Placeholder text used in the filter input when filtering is enabled.
- Attribute
- filter-placeholder
- Default value
- ""
- Example
- <arcgis-layer-list-next filter-placeholder="Search..."></arcgis-layer-list-next>layerListNextElement.filterPlaceholder = "Search...";
filterText
- Type
- string
The value of the filter input text string when filtering is enabled.
- Attribute
- filter-text
- Default value
- ""
- Example
- reactiveUtils.watch(() => layerListNextElement.filterText,(filterText) => console.log(filterText));
headingLevel
- Type
- HeadingLevel
Indicates the heading level to use for the heading of the component. By default, the heading is rendered as a <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
- Attribute
- heading-level
- Default value
- 2
- Example
- <arcgis-layer-list-next heading-level="2"></arcgis-layer-list-next>layerListNextElement.headingLevel = 2;
hideCatalogLayerList
- Type
- boolean
Indicates whether to hide the catalog layer list in the component.
- Attribute
- hide-catalog-layer-list
- Default value
- false
- Example
- <arcgis-layer-list-next hide-catalog-layer-list></arcgis-layer-list-next>layerListNextElement.hideCatalogLayerList = true;
hideNoFilterResultsNotice
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Indicates whether to hide the notice that appears when no results are found after filtering.
- Attribute
- hide-no-filter-results-notice
- Default value
- false
- Example
- <arcgis-layer-list-next hide-no-filter-results-notice></arcgis-layer-list-next>layerListNextElement.hideNoFilterResultsNotice = true;
hideNoItemsNotice
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Indicates whether to hide the notice that appears when there are no items to display.
- Attribute
- hide-no-items-notice
- Default value
- false
- Example
- <arcgis-layer-list-next hide-no-items-notice></arcgis-layer-list-next>layerListNextElement.hideNoItemsNotice = true;
hideStatusIndicators
- Type
- boolean
Indicates whether to hide status indicators in the component.
- Attribute
- hide-status-indicators
- Default value
- false
- Example
- <arcgis-layer-list-next hide-status-indicators></arcgis-layer-list-next>layerListNextElement.hideStatusIndicators = true;
icon
- 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
- Attribute
- icon
- Default value
- "layers"
knowledgeGraphOptions
- Type
- TableListParams | undefined
KnowledgeGraphLayer specific properties. KnowledgeGraphLayer#tables are displayed as an expandable arcgis-table-list-next 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-next.
- See also
arcgis-table-list-next 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,}
listItemCreatedFunction
- Type
- ItemModifier | null | undefined
A function that executes each time a list item is created. Use this function to configure the list item, including its title, actions, and panels.
- Example
- layerListNextElement.listItemCreatedFunction = async (event) => {// Destructure the item from the event objectconst {item} = event;// Wait for the layer to load and the item title to become availableawait item.layer.when();// If the item's title matches "US Demographics", customize the list itemif (item.title === "US Demographics") {// open the list item in the LayerList componentitem.open = true;// change the title to something more descriptiveitem.title = "Population by county";// set an action for zooming to the full extent of the layeritem.actionsSections = [[{title: "Go to full extent",icon: "zoom-out-fixed",id: "full-extent"}]];}};
listModeDisabled
- Type
- boolean
- Since
- ArcGIS Maps SDK for JavaScript 5.2
Specifies whether to ignore the listMode property to display all layers. A common use case for listModeDisabled is when you want to use the component to manage and configure a layer's listMode value.
- See also
- Attribute
- list-mode-disabled
- Default value
- false
- Example
- <arcgis-layer-list-next list-mode-disabled></arcgis-layer-list-next>layerListNextElement.listModeDisabled = true;
minDragEnabledItems
- Type
- number
The minimum number of list items required to enable drag and drop reordering.
- Attribute
- min-drag-enabled-items
- Default value
- 2
- Example
- <arcgis-layer-list-next min-drag-enabled-items="5"></arcgis-layer-list-next>layerListNextElement.minDragEnabledItems = 5;
minFilterItems
- Type
- number
The minimum number of list items required to display the filter input box.
- Attribute
- min-filter-items
- Default value
- 10
- Example
- <arcgis-layer-list-next min-filter-items="3"></arcgis-layer-list-next>layerListNextElement.minFilterItems = 3;
openedLayers
- Type
- Collection<FlowLayer>
A collection of layers opened in a flow item within the component. Use this property to navigate back programmatically by removing the last opened layer.
- See also
- Example
- // back out of the flow item to the main layer listlayerListNext.openedLayers.pop();
operationalItems
- Type
- Collection<Item>
A collection of items representing the operational layers in the layer list.
- Example
- layerListElement.operationalItems.forEach(item => console.log(item.title));
referenceElement
- 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.
- Attribute
- reference-element
selectedItems
- Type
- Collection<Item>
A collection of selected items in the list. This collection is updated when the user changes selection and is only populated when selectionMode is not set to "none".
- See also
- Example
- reactiveUtils.watch(() => layerListNext.selectedItems?.at(0)?.layer,(layer) => {layer && handleLayerSelection(layer);},);
selectionMode
- 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
- Attribute
- selection-mode
- Default value
- "none"
- Example
- <arcgis-layer-list-next selection-mode="multiple"></arcgis-layer-list-next>layerListNextElement.selectionMode = "multiple";
showCloseButton
- Type
- boolean
This property provides the ability to show or hide the close button. When the close button is shown, the ESC key can be used to close the component via keyboard when the focus is within the component.
- Attribute
- show-close-button
- Default value
- false
- Example
- <arcgis-layer-list-next show-close-button></arcgis-layer-list-next>layerListNextElement.showCloseButton = true;
showCollapseButton
- Type
- boolean
This property provides the ability to show or hide the collapse button.
- Attribute
- show-collapse-button
- Default value
- false
- Example
- <arcgis-layer-list-next show-collapse-button></arcgis-layer-list-next>layerListNextElement.showCollapseButton = true;
showErrors
- Type
- boolean
This property provides the ability to show or hide layer error indicators.
- Attribute
- show-errors
- Default value
- false
- Example
- <arcgis-layer-list-next show-errors></arcgis-layer-list-next>layerListNextElement.showErrors = true;
showFilter
- Type
- boolean
This property provides the ability to show or hide the filter input box when then number of list items is equal to or greater than the value set in minFilterItems, allowing users to filter layers by their title.
- Attribute
- show-filter
- Default value
- false
- Example
- <arcgis-layer-list-next show-filter></arcgis-layer-list-next>layerListNextElement.showFilter = true;
showHeading
- Type
- boolean
This property provides the ability to show or hide the heading.
- Attribute
- show-heading
- Default value
- false
- Example
- <arcgis-layer-list-next show-heading></arcgis-layer-list-next>layerListNextElement.showHeading = true;
showTemporaryLayerIndicators
- Type
- boolean
This property provides the ability to show or hide the temporary layer indicators for layers with Layer#persistenceEnabled set to false. A temporary icon will be displayed on the near side of the layer title.
- Attribute
- show-temporary-layer-indicators
- Default value
- false
- Example
- <arcgis-layer-list-next show-temporary-layer-indicators></arcgis-layer-list-next>layerListNextElement.showTemporaryLayerIndicators = true;
tableList
- Type
- ArcgisTableListNext | undefined
The arcgis-table-list-next 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.

- See also
knowledgeGraphOptions for configuring the table list and its items.
- Example
- // Use reactiveUtils to respond to the layerListElement.tableList "arcgisTriggerAction" eventconst tableListActionHandle = reactiveUtils.on(() => layerListElement.tableList,"arcgisTriggerAction",(event) => {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.tableListconst tableSelectionWatchHandle = reactiveUtils.watch(() => layerListElement.tableList?.selectedItems?.at(0)?.layer,(layer) => {layer && handleLayerSelection(layer);},);layerListHandles.push(tableSelectionWatchHandle);
view
- 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
viewproperty 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 theviewproperty.
visibilityAppearance
- 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
- <arcgis-layer-list-next visibility-appearance="checkbox"></arcgis-layer-list-next>layerListNextElement.visibilityAppearance = "checkbox";
Methods
| Method | Signature |
|---|---|
| inherited | componentOnReady(): Promise<this> |
| destroy(): Promise<void> |
componentOnReady
- Signature
-
componentOnReady (): Promise<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!");
Events
| Name | Type |
|---|---|
| CustomEvent<{ name: "state"; }> | |
| CustomEvent<LayerListModelEvents["trigger-action"]> |
arcgisClose
arcgisClose: CustomEvent<void> Emitted when the component's close button is clicked.
arcgisFilterChange
arcgisFilterChange: CustomEvent<void> - Since
- ArcGIS Maps SDK for JavaScript 5.2
Emitted when the value of the filterText input changes.
arcgisOpenedLayersChange
arcgisOpenedLayersChange: CustomEvent<void> - Since
- ArcGIS Maps SDK for JavaScript 5.2
Emitted when the collection of openedLayers changes.
arcgisPropertyChange
arcgisPropertyChange: CustomEvent<{ name: "state"; }> Emitted when the value of a property is changed. Use this to listen to changes to properties.
arcgisReady
arcgisReady: CustomEvent<void> Emitted when the component associated with a map or scene view is ready for user interaction.
arcgisSelectedItemsChange
arcgisSelectedItemsChange: CustomEvent<void> - Since
- ArcGIS Maps SDK for JavaScript 5.2
Emitted when the collection of selectedItems changes.
arcgisTriggerAction
arcgisTriggerAction: CustomEvent<LayerListModelEvents["trigger-action"]> Emitted when an action is triggered on the component.

