ESM
import "@arcgis/map-components/components/arcgis-basemap-layer-list-next";
Inheritance
ArcgisBasemapLayerListNext→HTMLElement
Since
ArcGIS Maps SDK for JavaScript 5.2
beta

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

PropertyAttributeType
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

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

baseFilterPredicate

Property
Type
FilterPredicate | undefined

Specifies a function to handle filtering base layer items.

Example
basemapLayerListElement.baseFilterPredicate = (item) => item.title.toLowerCase().includes("streets");

baseFilterText

Property
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

Property
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 title
baseListItem.title = "World Imagery";
// open the baseList item
baseListItem.open = true;
}
}

baseItems

readonly Property
Type
Collection<Item>

A collection of items representing the base layers.

Example
basemapLayerListElement.baseItems.forEach(item => console.log(item.title));

basemapTitle

Property
Type
string | null | undefined

The current basemap's title.

Attribute
basemap-title
Example
<arcgis-basemap-layer-list-next basemap-title="My Basemap"></arcgis-basemap-layer-list-next>
basemapLayerListElement.basemapTitle = "My Basemap";

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 basemapLayerListElement.catalogLayerList "arcgisTriggerAction" event
const 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.catalogLayerList
const catalogSelectionWatchHandle = reactiveUtils.watch(
() =>
basemapLayerListElement.catalogLayerList?.selectedItems?.at(0)?.layer,
(layer) => {
layer && handleLayerSelection(layer);
},
);
basemapLayerListHandles.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-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.

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

Property
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

reflected 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-basemap-layer-list-next collapsed></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.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.

Attribute
drag-enabled
Default value
false
Example
<arcgis-basemap-layer-list-next drag-enabled></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.dragEnabled = true;

editingTitle

Property
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

Property
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

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-basemap-layer-list-next heading-level="2"></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.headingLevel = 2;

hideBaseLayers

Property
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

Property
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

Property
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

Property
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

Property
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

Property
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

Property
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

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"

label

Property
Type
string | undefined

The component's default label.

Attribute
label

listModeDisabled

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

messageOverrides

Property
Type
Record<string, unknown> | undefined

Replace localized message strings with your own strings.

Note: Individual message keys may change between releases.

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-basemap-layer-list-next min-filter-items="3"></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.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
basemapLayerListNext.openedLayers.pop();

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

referenceFilterPredicate

Property
Type
FilterPredicate | undefined

Specifies a function to handle filtering reference layer items.

Example
basemapLayerListElement.referenceFilterPredicate = (item) => item.title.toLowerCase().includes("streets");

referenceFilterText

Property
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

Property
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 title
referenceListItem.title = "Reference layer";
// open the reference list item
referenceListItem.open = true;
}
}

referenceItems

readonly Property
Type
Collection<Item>

A collection of items representing the reference layers.

Example
basemapLayerListElement.referenceItems.forEach(item => console.log(item.title));

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(
() => basemapLayerListNext.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-basemap-layer-list-next selection-mode="multiple"></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.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-basemap-layer-list-next show-close-button></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.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-basemap-layer-list-next show-collapse-button></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.showCollapseButton = true;

showEditTitleButton

Property
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

Property
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

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-basemap-layer-list-next show-filter></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.showFilter = 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-basemap-layer-list-next show-temporary-layer-indicators></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.showTemporaryLayerIndicators = true;

state

readonly Property
Type
State

The current state of the component.

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-basemap-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-basemap-layer-list-next visibility-appearance="checkbox"></arcgis-basemap-layer-list-next>
basemapLayerListNextElement.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 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!");

destroy

Method
Signature
destroy (): Promise<void>

Permanently destroy the component.

Returns
Promise<void>

Events

arcgisBaseFilterChange

Event
arcgisBaseFilterChange: CustomEvent<void>

Emitted when the value of the baseFilterText changes.

bubbles composed cancelable

arcgisClose

Event
arcgisClose: CustomEvent<void>

Emitted when the component's close button is clicked.

bubbles composed cancelable

arcgisOpenedLayersChange

Event
arcgisOpenedLayersChange: CustomEvent<void>

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

arcgisReferenceFilterChange

Event
arcgisReferenceFilterChange: CustomEvent<void>

Emitted when the value of the referenceFilterText changes.

bubbles composed cancelable

arcgisTriggerAction

Event

Emitted when an action is triggered on the component.

bubbles composed cancelable