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

Keyboard Navigation

Demo

Properties

PropertyAttributeType
auto-destroy-disabled
readonly
closed
collapsed
drag-enabled
filter-placeholder
((item: Item | TableItem) => boolean) | undefined
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

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
Example
<arcgis-layer-list-next auto-destroy-disabled></arcgis-layer-list-next>
layerListNextElement.autoDestroyDisabled = true;

catalogLayerList

readonly Property
Type
ArcgisCatalogLayerListNext | undefined

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.

See also
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,
(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-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.

See also
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

Property
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

Property
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

Property
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

Property
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...";

filterPredicate

Property
Type
((item: Item | TableItem) => boolean) | undefined

Specifies a function to determine whether a list item should be included in filter results.

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

filterText

Property
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

Property
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

Property
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

Property
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

Property
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

Property
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

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
Attribute
icon
Default value
"layers"

knowledgeGraphOptions

Property
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
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
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 object
const {item} = event;
// Wait for the layer to load and the item title to become available
await item.layer.when();
// If the item's title matches "US Demographics", customize the list item
if (item.title === "US Demographics") {
// open the list item in the LayerList component
item.open = true;
// change the title to something more descriptive
item.title = "Population by county";
// set an action for zooming to the full extent of the layer
item.actionsSections = [[{
title: "Go to full extent",
icon: "zoom-out-fixed",
id: "full-extent"
}]];
}
};

listModeDisabled

Property
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;

messageOverrides

Property
Type
Record<string, unknown> | undefined
Since
ArcGIS Maps SDK for JavaScript 5.2

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

minDragEnabledItems

Property
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

Property
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

readonly Property
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 list
layerListNext.openedLayers.pop();

operationalItems

readonly Property
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

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
Attribute
reference-element

selectedItems

Property
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

Property
Type
List["selectionMode"]

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

ValueDescription
multipleAllows 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.
noneDisables selection. Use this when you want to prevent selecting items.
singleAllows 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-persistAllows 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

Property
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

Property
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

Property
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

Property
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

Property
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

Property
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;

state

readonly Property
Type
State

The current state of the component.

tableList

readonly Property
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.

tableList

See also
Example
// Use reactiveUtils to respond to the layerListElement.tableList "arcgisTriggerAction" event
const 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.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.

ValueDescriptionExample
defaultDisplays 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.visibilityAppearance-default
checkboxDisplays checkbox icons on the near side. See check-square-f and square calcite icons.visibilityAppearance-checkbox
Attribute
visibility-appearance
Default value
"default"
Example
<arcgis-layer-list-next visibility-appearance="checkbox"></arcgis-layer-list-next>
layerListNextElement.visibilityAppearance = "checkbox";

Methods

MethodSignature
inherited
componentOnReady(): Promise<this>
destroy(): Promise<void>

componentOnReady

inherited Method
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!");

destroy

Method
Signature
destroy (): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

Events

arcgisClose

Event
arcgisClose: CustomEvent<void>

Emitted when the component's close button is clicked.

bubbles composed cancelable

arcgisFilterChange

Event
arcgisFilterChange: CustomEvent<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Emitted when the value of the filterText input changes.

bubbles composed cancelable

arcgisOpenedLayersChange

Event
arcgisOpenedLayersChange: CustomEvent<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Emitted when the collection of openedLayers changes.

bubbles composed cancelable

arcgisPropertyChange

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

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

bubbles composed cancelable

arcgisReady

Event
arcgisReady: CustomEvent<void>

Emitted when the component associated with a map or scene view is ready for user interaction.

bubbles composed cancelable

arcgisSelectedItemsChange

Event
arcgisSelectedItemsChange: CustomEvent<void>
Since
ArcGIS Maps SDK for JavaScript 5.2

Emitted when the collection of selectedItems changes.

bubbles composed cancelable

arcgisTriggerAction

Event
arcgisTriggerAction: CustomEvent<LayerListModelEvents["trigger-action"]>

Emitted when an action is triggered on the component.

bubbles composed cancelable