arcgis-selection-list | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/map-components/components/arcgis-selection-list";

Inheritance: ArcgisSelectionList→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The Selection List component displays selected features in a hierarchical list organized by group and layer. It is intended for applications that need to present the current selection and support browsing, filtering, and interaction with selected features.

The component can be used with the Map or Scene component and reflects selections made through a selection manager, including the view, the Selection Toolbar, or the selection manager API.

See also

Sample - Selection List Component

Demo

Properties

Property	Attribute	Type
activeLayerItem readonly		LayerItem \| null \| undefined
afterListItemSelect		ListItemSelectCallback \| undefined
allLayerItems readonly		ParentItem[]
autoDestroyDisabled	auto-destroy-disabled	boolean
count readonly		number
disabled	disabled	boolean
displayMode	display-mode	"feature" \| "group" \| "layer"
effectiveSelectionManager readonly		null \| undefined \| SelectionManager
filterText	filter-text	string \| undefined
hideChip	hide-chip	boolean
hideChipCloseButton	hide-chip-close-button	boolean
hideFilter	hide-filter	boolean
hideFilterNotice	hide-filter-notice	boolean
hideHeader	hide-header	boolean
hideItemCloseActions	hide-item-close-actions	boolean
hideItemCount	hide-item-count	boolean
hideItemIcons	hide-item-icons	boolean
hideItemMenus	hide-item-menus	boolean
hideLayerFilter	hide-layer-filter	boolean
hideMenu	hide-menu	boolean
hideZoomToButton	hide-zoom-to-button	boolean
highlightOnHoverDisabled	highlight-on-hover-disabled	boolean
icon	icon	IconName \| undefined
label	label	string \| undefined
layer		SelectableLayer \| null \| undefined
layerItems readonly		LayerItem[]
listItemActionConfigurations		ListItemActionConfiguration[] \| undefined
listItemUnavailableFunction		ListItemUnavailableFunction \| undefined
maxVisibleFeatureCountExceeded readonly		boolean
maxVisibleFeatureCountPerLayer	max-visible-feature-count-per-layer	number
menuScale	menu-scale	Action["scale"]
referenceElement	reference-element	ArcgisReferenceElement \| string \| undefined
selectionManager		SelectionManager \| null \| undefined
state readonly		"disabled" \| "error" \| "loading" \| "ready"
view		SelectableViewUnion \| null \| undefined
visibleFeatureCount readonly		number
visibleFeatureItems readonly		FeatureItem[]
visibleLayerCount readonly		number
visualScale	visual-scale	Action["scale"]

activeLayerItem

readonly Property

Type: LayerItem | null | undefined

Reference to a single layer item being displayed in the list, if the layer property is set and that layer has selected features.

afterListItemSelect

Property

Type: ListItemSelectCallback | undefined

An optional function that runs when a user selects a feature, layer, or group item in the selection list itself. It does not run when a feature becomes selected through the arcgis-selection-toolbar, map click, or selection manager API.

allLayerItems

readonly Property

Type: ParentItem[]

Items representing all individual layer and group layers with an active selection.

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-selection-list auto-destroy-disabled></arcgis-selection-list>

selectionListElement.autoDestroyDisabled = true;

count

readonly Property

Type: number

Total number of selected features.

disabled

Property

Type: boolean

When true, the component is visually de-emphasized and does not accept user interaction.

Attribute: disabled
Default value: false

displayMode

Property

Type: "feature" | "group" | "layer"

Controls how the list is displayed. If this value is set to "group", the list displays feature and layer items nested under their associated layer and group items. If this value is set to "layer", the list displays feature items nested under their associated layer item, while excluding group items. If this value is set to "feature" the list only displays feature items, while excluding group and layer items.

Attribute: display-mode
Default value: "group"

effectiveSelectionManager

readonly Property

Type: null | undefined | SelectionManager

Reference to the selection manager being represented by the component.

filterText

Property

Type: string | undefined

Current value of the list's text filter.

Attribute: filter-text

hideChip

Property

Type: boolean

Indicates whether the selection count chip should be hidden. The chip shows the total count of selected features and a close button for clearing the selection.

Attribute: hide-chip
Default value: false

hideChipCloseButton

Property

Type: boolean

Indicates whether the 'close' button on the selection count chip should be hidden. The 'close' button allows users to clear the current selection.

Attribute: hide-chip-close-button
Default value: false

hideFilter

Property

Type: boolean

Indicates that the filter should be hidden.

Attribute: hide-filter
Default value: false

hideFilterNotice

Property

Type: boolean

Indicates that the filter notice should be hidden.

Attribute: hide-filter-notice
Default value: false

hideHeader

Property

Type: boolean

Indicates that the header should be hidden.

Attribute: hide-header
Default value: false

hideItemCloseActions

Property

Type: boolean

Indicates that the close actions for individual list items should be hidden.

Attribute: hide-item-close-actions
Default value: false

hideItemCount

Property

Type: boolean

Indicates that the count for individual list items should be hidden.

Attribute: hide-item-count
Default value: false

hideItemIcons

Property

Type: boolean

Indicates that the icons for individual list items should be hidden.

Attribute: hide-item-icons
Default value: false

hideItemMenus

Property

Type: boolean

Indicates that the menus for individual list items should be hidden.

Attribute: hide-item-menus
Default value: false

hideLayerFilter

Property

Type: boolean

Indicates that the layer filter should be hidden.

Attribute: hide-layer-filter
Default value: false

hideMenu

Property

Type: boolean

Indicates that the primary menu should be hidden.

Attribute: hide-menu
Default value: false

hideZoomToButton

Property

Type: boolean

Indicates that the 'zoom to' button should be hidden.

Attribute: hide-zoom-to-button
Default value: false

highlightOnHoverDisabled

Property

Type: boolean

Property controlling whether corresponding features on the view should not be highlighted when hovering over the associated list item. Only applies to list items representing individual features.

Attribute: highlight-on-hover-disabled
Default value: false

icon

Property

Type: IconName | undefined

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: "selection"

label

Property

Type: string | undefined

The component's default label.

Attribute: label

layer

Property

Type: SelectableLayer | null | undefined

Setting this property causes the list to only display features from this layer. If there are no selected features from this layer, the full list will appear. This value also reflects when a layer is selected from the layer dropdown.

layerItems

readonly Property

Type: LayerItem[]

Items representing individual layers with an active selection.

listItemActionConfigurations

Property

Type: ListItemActionConfiguration[] | undefined

Used to display additional dropdown items in the dropdown associated with each list item.

listItemUnavailableFunction

Property

Type: ListItemUnavailableFunction | undefined

Used to set the unavailable property for each list item.

maxVisibleFeatureCountExceeded

readonly Property

Type: boolean

Indicates the list is only showing a subset of selected feature items due to the selection being greater than the current value of the maxVisibleFeatureCountPerLayer property. This value also accounts for any active filters.

Default value: false

maxVisibleFeatureCountPerLayer

Property

Type: number

Maximum number of selected feature items displayed per layer. Does not limit or restrict the selection itself.

Attribute: max-visible-feature-count-per-layer

menuScale

Property

Type: Action["scale"]

Default scale of all menus.

Attribute: menu-scale
Default value: "m"

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

selectionManager

Property

Type: SelectionManager | null | undefined

A reference to a custom selection manager to use instead of the view's default selection manager.

state

readonly Property

Type: "disabled" | "error" | "loading" | "ready"

Reflects the component's current state. Possible values are:

"disabled": The component is not interactive.
"error": The component has encountered an error.
"loading": The component is in a loading state.
"ready": The component is ready for interaction.

view

Property

Type: SelectableViewUnion | 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-selection-list component will be associated with a map or scene component rather than using the view property.

visibleFeatureCount

readonly Property

Type: number

Total number of visible feature items in the list.

visibleFeatureItems

readonly Property

Type: FeatureItem[]

Visible feature items in the list, accounting for maxVisibleFeatureCountPerLayer. Excludes feature items hidden by the filter.

visibleLayerCount

readonly Property

Type: number

Count for total number of visible layer items in the list, excluding group layer items.

visualScale

Property

Type: Action["scale"]

Controls the visual scale of any rendered Calcite elements.

Attribute: visual-scale
Default value: "s"

Methods

Method	Signature
clear	clear(): Promise<void>
collapseAll	collapseAll(): Promise<void>
componentOnReady inherited	componentOnReady(): Promise<this>
deselectItem	deselectItem(item: ListItem): Promise<void>
destroy	destroy(): Promise<void>
expandAll	expandAll(): Promise<void>
findLayerItem	findLayerItem(layer: SelectableLayer): Promise<LayerItem \| null \| undefined>
findParentItem	findParentItem(layer: SelectableLayer): Promise<null \| undefined \| ParentItem>
goToItem	goToItem(item: ListItem): Promise<void>
removeFromSelection	removeFromSelection(params: { layer: SelectableLayer; selection: SelectionIdentifier[]; }): Promise<void>
replace	replace(params: { layer: SelectableLayer; selection: SelectionIdentifier[]; }): Promise<void>
selectItem	selectItem(item: ListItem): Promise<void>

clear

Method

Signature: clear (): Promise<void>

Clears all active selections for all groups, layers and features.

Returns: Promise<void>

collapseAll

Method

Signature: collapseAll (): Promise<void>

Utility method for collapsing all parent list items.

Returns: 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 arcgisSelectionList = document.createElement("arcgis-selection-list");
document.body.append(arcgisSelectionList);
await arcgisSelectionList.componentOnReady();
console.log("arcgis-selection-list is ready to go!");

deselectItem

Method

Signature: deselectItem (item: ListItem): Promise<void>

Utility method to deselect any group, layer or feature item.

Parameters

Parameter	Type	Description	Required
item	ListItem	The list item to deselect.

Returns: Promise<void>

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

expandAll

Method

Signature: expandAll (): Promise<void>

Utility method for expanding all parent list items.

Returns: Promise<void>

findLayerItem

Method

Signature: findLayerItem (layer: SelectableLayer): Promise<LayerItem | null | undefined>

Utility method for finding the corresponding LayerItem for a given layer.

Parameters

Parameter	Type	Description	Required
layer	SelectableLayer	The layer for which to find the corresponding LayerItem.

Returns: Promise<LayerItem | null | undefined>
The LayerItem associated with the provided layer.

findParentItem

Method

Signature: findParentItem (layer: SelectableLayer): Promise<null | undefined | ParentItem>

Utility method for finding the corresponding parent item for a given layer.

Parameters

Parameter	Type	Description	Required
layer	SelectableLayer	The layer for which to find the corresponding parent item.

Returns: Promise<null | undefined | ParentItem>
The parent item associated with the provided layer.

goToItem

Method

Signature: goToItem (item: ListItem): Promise<void>

Repositions the view to center based on the chosen item.

Parameters

Parameter	Type	Description	Required
item	ListItem	The list item for which to reposition the view.

Returns: Promise<void>

removeFromSelection

Method

Signature: removeFromSelection (params: { layer: SelectableLayer; selection: SelectionIdentifier[]; }): Promise<void>

Removes specific features from the selection, based on the provided layer and object IDs.

Parameters

Parameter	Type	Description	Required
params	{ layer: SelectableLayer; selection: SelectionIdentifier[]; }	An object containing the layer and selection to remove.

Returns: Promise<void>

replace

Method

Signature: replace (params: { layer: SelectableLayer; selection: SelectionIdentifier[]; }): Promise<void>

Replaces an active selection, based on the provided layer and object IDs.

Parameters

Parameter	Type	Description	Required
params	{ layer: SelectableLayer; selection: SelectionIdentifier[]; }	An object containing the layer and selection to replace.

Returns: Promise<void>

selectItem

Method

Signature: selectItem (item: ListItem): Promise<void>

Selects all features contextual to a given item. Deselects all other features.

Parameters

Parameter	Type	Description	Required
item	ListItem	The list item for which to select all features.

Returns: Promise<void>

Events

Name	Type
arcgisClear	CustomEvent<void>
arcgisPropertyChange	CustomEvent<{ name: "state"; }>
arcgisReady	CustomEvent<void>

arcgisClear

Event

arcgisClear: CustomEvent<void>

Fires when the active selection is cleared via the close button on the selection count chip. This event does not fire when the selection is cleared programmatically, or when the selection is cleared by a different component. For more information about selection changes, use the selection-change event emitted by the associated selection manager.

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 for user interaction.