▾
import "@arcgis/map-components/components/arcgis-basemap-layer-list-next";- Inheritance
- ArcgisBasemapLayerListNext→
HTMLElement
- Since
- ArcGIS Maps SDK for JavaScript 5.2
The Basemap Layer List (next) component is the successor to the Basemap Layer List component, provided to you early for testing and feedback.
In version 6.0, the implementation of arcgis-basemap-layer-list will be updated under the hood to that of arcgis-basemap-layer-list-next,
and this component will be removed. There is a breaking change in the name of the events for catalogLayerList compared to the arcgis-basemap-layer-list.
To update at version 6.0, simply remove -next from the component name.
The Basemap Layer List (next) component provides a way to display a list of Basemap layers and switch on/off their visibility. Base layers and reference layers are divided into separate sections.
Demo
Properties
| Property | Attribute | Type |
|---|---|---|
| auto-destroy-disabled | ||
| | ||
| base-filter-text | ||
| | ||
| readonly | | |
| basemap-title | ||
| readonly | | |
| | ||
| closed | ||
| reflected | collapsed | |
| drag-enabled | ||
| editing-title | ||
| filter-placeholder | ||
| heading-level | ||
| hide-base-layers | ||
| hide-catalog-layer-list | ||
| hide-heading | ||
| hide-no-filter-results-notice | ||
| hide-no-items-notice | ||
| hide-reference-layers | ||
| hide-status-indicators | ||
| icon | ||
| label | ||
| list-mode-disabled | ||
| | ||
| min-filter-items | ||
| readonly | | |
| reference-element | ||
| | ||
| reference-filter-text | ||
| | ||
| readonly | | |
| | ||
| selection-mode | List["selectionMode"] | |
| show-close-button | ||
| show-collapse-button | ||
| show-edit-title-button | ||
| show-errors | ||
| show-filter | ||
| show-temporary-layer-indicators | ||
| 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-basemap-layer-list-next auto-destroy-disabled></arcgis-basemap-layer-list-next>basemapLayerListNextElement.autoDestroyDisabled = true;
baseFilterPredicate
- Type
- FilterPredicate | undefined
Specifies a function to handle filtering base layer items.
- Example
- basemapLayerListElement.baseFilterPredicate = (item) => item.title.toLowerCase().includes("streets");
baseFilterText
- Type
- string
The value of the base layers filter input text string if showFilter is true.
- See also
- Attribute
- base-filter-text
- Default value
- ""
- Example
- reactiveUtils.watch(() => basemapLayerListElement.baseFilterText,(baseFilterText) => console.log(baseFilterText));
baseItemCreatedFunction
- Type
- ItemModifier | null | undefined
Specifies a function that accesses each Item representing a base layer. Each list item's modifiable properties can be updated within. Actions can be added to list items using the actionsSections property of the Item.
- Example
- basemapLayerListElement.baseItemCreatedFunction = (event) => {const baseListItem = event.item;if(baseListItem.title === "World Imagery_01"){// clean up titlebaseListItem.title = "World Imagery";// open the baseList itembaseListItem.open = true;}}
baseItems
- Type
- Collection<Item>
A collection of items representing the base layers.
- Example
- basemapLayerListElement.baseItems.forEach(item => console.log(item.title));
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 basemapLayerListElement.catalogLayerList "arcgisTriggerAction" eventconst catalogLayerListActionHandle = reactiveUtils.on(() => basemapLayerListElement.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`);}basemapLayerListElement?.openedLayers?.pop();}},);basemapLayerListHandles.push(catalogLayerListActionHandle);// Use reactiveUtils to watch for a selected item in the basemapLayerListElement.catalogLayerListconst catalogSelectionWatchHandle = reactiveUtils.watch(() =>basemapLayerListElement.catalogLayerList?.selectedItems?.at(0)?.layer,(layer) => {layer && handleLayerSelection(layer);},);basemapLayerListHandles.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-basemap-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
- basemapLayerListElement.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-basemap-layer-list-next closed></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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-basemap-layer-list-next collapsed></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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.
- Attribute
- drag-enabled
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next drag-enabled></arcgis-basemap-layer-list-next>basemapLayerListNextElement.dragEnabled = true;
editingTitle
- Type
- boolean
Indicates whether the form to edit the basemap's title is currently visible. Any edits made will only be shown locally and will not be saved.
- See also
- Attribute
- editing-title
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next editing-title></arcgis-basemap-layer-list-next>basemapLayerListElement.editingTitle = true;
filterPlaceholder
- Type
- string
Placeholder text used in the filter input when filtering is enabled.
- Attribute
- filter-placeholder
- Default value
- ""
- Example
- <arcgis-basemap-layer-list-next filter-placeholder="Search..."></arcgis-basemap-layer-list-next>basemapLayerListNextElement.filterPlaceholder = "Search...";
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-basemap-layer-list-next heading-level="2"></arcgis-basemap-layer-list-next>basemapLayerListNextElement.headingLevel = 2;
hideBaseLayers
- Type
- boolean
This property provides the ability to show or hide the base layers.
- Attribute
- hide-base-layers
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next hide-base-layers></arcgis-basemap-layer-list-next>basemapLayerListElement.hideBaseLayers = true;
hideCatalogLayerList
- Type
- boolean
Indicates whether to hide the catalog layer list in the component.
- Attribute
- hide-catalog-layer-list
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next hide-catalog-layer-list></arcgis-basemap-layer-list-next>basemapLayerListNextElement.hideCatalogLayerList = true;
hideHeading
- Type
- boolean
Indicates whether to hide the component's heading.
- Attribute
- hide-heading
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next hide-heading></arcgis-basemap-layer-list-next>basemapLayerListNextElement.hideHeading = true;
hideNoFilterResultsNotice
- Type
- boolean
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-basemap-layer-list-next hide-no-filter-results-notice></arcgis-basemap-layer-list-next>basemapLayerListNextElement.hideNoFilterResultsNotice = true;
hideNoItemsNotice
- Type
- boolean
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-basemap-layer-list-next hide-no-items-notice></arcgis-basemap-layer-list-next>basemapLayerListNextElement.hideNoItemsNotice = true;
hideReferenceLayers
- Type
- boolean
This property provides the ability to show or hide the reference layers.
- Attribute
- hide-reference-layers
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next hide-reference-layers></arcgis-basemap-layer-list-next>basemapLayerListElement.hideReferenceLayers = true;
hideStatusIndicators
- Type
- boolean
Indicates whether to hide status indicators in the component.
- Attribute
- hide-status-indicators
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next hide-status-indicators></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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"
listModeDisabled
- Type
- boolean
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-basemap-layer-list-next list-mode-disabled></arcgis-basemap-layer-list-next>basemapLayerListNextElement.listModeDisabled = true;
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-basemap-layer-list-next min-filter-items="3"></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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 listbasemapLayerListNext.openedLayers.pop();
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
referenceFilterPredicate
- Type
- FilterPredicate | undefined
Specifies a function to handle filtering reference layer items.
- Example
- basemapLayerListElement.referenceFilterPredicate = (item) => item.title.toLowerCase().includes("streets");
referenceFilterText
- Type
- string
The value of the reference layers filter input text string if showFilter is true.
- See also
- Attribute
- reference-filter-text
- Default value
- ""
- Example
- reactiveUtils.watch(() => basemapLayerListElement.referenceFilterText,(referenceFilterText) => console.log(referenceFilterText));
referenceItemCreatedFunction
- Type
- ItemModifier | null | undefined
Specifies a function that accesses each Item representing a reference layer. Each list item's modifiable properties can be updated within. Actions can be added to list items using the actionsSections property.
- Example
- basemapLayerListElement.referenceItemCreatedFunction = (event) => {const referenceListItem = event.item;if(referenceListItem.title === "World Imagery_01_reference_layer"){// clean up titlereferenceListItem.title = "Reference layer";// open the reference list itemreferenceListItem.open = true;}}
referenceItems
- Type
- Collection<Item>
A collection of items representing the reference layers.
- Example
- basemapLayerListElement.referenceItems.forEach(item => console.log(item.title));
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(() => basemapLayerListNext.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-basemap-layer-list-next selection-mode="multiple"></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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-basemap-layer-list-next show-close-button></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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-basemap-layer-list-next show-collapse-button></arcgis-basemap-layer-list-next>basemapLayerListNextElement.showCollapseButton = true;
showEditTitleButton
- Type
- boolean
This property provides the ability to show or hide the edit title button in the header.
- See also
- Attribute
- show-edit-title-button
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next show-edit-title-button></arcgis-basemap-layer-list-next>basemapLayerListElement.showEditTitleButton = true;
showErrors
- Type
- boolean
This property provides the ability to show or hide layer error indicators.
- Attribute
- show-errors
- Default value
- false
- Example
- <arcgis-basemap-layer-list-next show-errors></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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-basemap-layer-list-next show-filter></arcgis-basemap-layer-list-next>basemapLayerListNextElement.showFilter = 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-basemap-layer-list-next show-temporary-layer-indicators></arcgis-basemap-layer-list-next>basemapLayerListNextElement.showTemporaryLayerIndicators = true;
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-basemap-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-basemap-layer-list-next visibility-appearance="checkbox"></arcgis-basemap-layer-list-next>basemapLayerListNextElement.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 arcgisBasemapLayerListNext = document.createElement("arcgis-basemap-layer-list-next");document.body.append(arcgisBasemapLayerListNext);await arcgisBasemapLayerListNext.componentOnReady();console.log("arcgis-basemap-layer-list-next is ready to go!");
Events
| Name | Type |
|---|---|
| CustomEvent<{ name: "state"; }> | |
arcgisBaseFilterChange
arcgisBaseFilterChange: CustomEvent<void> Emitted when the value of the baseFilterText changes.
arcgisClose
arcgisClose: CustomEvent<void> Emitted when the component's close button is clicked.
arcgisOpenedLayersChange
arcgisOpenedLayersChange: CustomEvent<void> 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.
arcgisReferenceFilterChange
arcgisReferenceFilterChange: CustomEvent<void> Emitted when the value of the referenceFilterText changes.
arcgisTriggerAction
arcgisTriggerAction: CustomEvent<BasemapLayerListTriggerActionEvent> Emitted when an action is triggered on the component.

