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

ESM

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

Inheritance: ArcgisSelectionToolbar→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The selection toolbar component can be used to modify selected features on a provided MapView or SceneView. It provides an interface for performing selection operations such as adding, removing, or replacing selected features. This component can be used in conjunction with other components, such as arcgis-selection-list and arcgis-feature-table.

Demo

Properties

Property	Attribute	Type
activeOperation readonly		SelectionOperation \| null \| undefined
autoDestroyDisabled	auto-destroy-disabled	boolean
availableOperationTypes		SelectionOperationType[]
continuousSelectionEnabled	continuous-selection-enabled	boolean
defaultLassoToolOptions		SelectionOperationProperties
defaultOperationType	default-operation-type	SelectionOperationType
defaultPointToolOptions		SelectionOperationProperties
defaultPolygonToolOptions		SelectionOperationProperties
defaultRectangleToolOptions		SelectionOperationProperties
disabled reflected	disabled	boolean
effectiveSelectionManager readonly		SelectionManager \| null \| undefined
effectiveSources readonly		Array<SelectionSource>
hideChip	hide-chip	boolean
hideChipCloseButton	hide-chip-close-button	boolean
hideLassoTool	hide-lasso-tool	boolean
hideOperationTypeControls	hide-operation-type-controls	boolean
hidePanTool	hide-pan-tool	boolean
hidePointTool	hide-point-tool	boolean
hidePolygonTool	hide-polygon-tool	boolean
hideProgress	hide-progress	boolean
hideRectangleTool	hide-rectangle-tool	boolean
icon	icon	IconName \| undefined
ignoreLayerVisibility	ignore-layer-visibility	boolean
label	label	string \| undefined
layerPreferenceEnabled	layer-preference-enabled	boolean
referenceElement	reference-element	ArcgisReferenceElement \| string \| undefined
returnFeatureTitleFields	return-feature-title-fields	boolean
returnGeometryDisabled	return-geometry-disabled	boolean
selectionManager		SelectionManager \| null \| undefined
sources		Array<SelectionSource> \| null \| undefined
state readonly		"active" \| "disabled" \| "ready"
syncResultsDisabled	sync-results-disabled	boolean
syncWhileDrawing	sync-while-drawing	boolean
view		SelectableViewUnion \| null \| undefined
visualScale	visual-scale	Action["scale"]

activeOperation

readonly Property

Type: SelectionOperation | null | undefined

A reference to the active selection operation. Only one selection operation can be active at a time.

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

selectionToolbarElement.autoDestroyDisabled = true;

availableOperationTypes

Property

Type: SelectionOperationType[]

An array of selection operation type names that determines what operation types appear in the associated dropdown component.

continuousSelectionEnabled

Property

Type: boolean

Determines if the selection toolbar should automatically reactivate a new selection operation after the completion of an active selection operation, using options from the previous operation. This only applies if the previous selection operation was completed, and not canceled.

Attribute: continuous-selection-enabled
Default value: false

defaultLassoToolOptions

Property

Type: SelectionOperationProperties

The default configuration for the lasso tool.

defaultOperationType

Property

Type: SelectionOperationType

The default selection operation type to use when starting a new selection operation. This value can be changed via the selection operation type dropdown.

Attribute: default-operation-type
Default value: "add"

defaultPointToolOptions

Property

Type: SelectionOperationProperties

The default configuration for the point tool.

defaultPolygonToolOptions

Property

Type: SelectionOperationProperties

The default configuration for the polygon tool.

defaultRectangleToolOptions

Property

Type: SelectionOperationProperties

The default configuration for the rectangle tool.

disabled

reflected Property

Type: boolean

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

Attribute: disabled
Default value: false

effectiveSelectionManager

readonly Property

Type: SelectionManager | null | undefined

A reference to the selection manager currently in use by the component.

effectiveSources

readonly Property

Type: Array<SelectionSource>

An array of validated selection sources. These sources will also include any relevant layer views that were found on the provided view if layerPreferenceEnabled is false.

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

hideLassoTool

Property

Type: boolean

Indicates whether the lasso tool should be hidden. The lasso tool allows for freehand selection of features.

Attribute: hide-lasso-tool
Default value: false

hideOperationTypeControls

Property

Type: boolean

Indicates whether the selection operation type controls should be hidden. The operation type controls allow for changing the selection operation type (e.g., replace, add, remove).

Attribute: hide-operation-type-controls
Default value: false

hidePanTool

Property

Type: boolean

Indicates whether the pan tool is hidden. The pan tool allows users to navigate the view without initiating a selection operation and is active by default when no selection operation is in progress.

Attribute: hide-pan-tool
Default value: false

hidePointTool

Property

Type: boolean

Indicates whether the point tool should be hidden. The point tool allows for selecting features by clicking on them. The point tool will include all features that intersect the selected point, rather than only the top-most feature.

Attribute: hide-point-tool
Default value: false

hidePolygonTool

Property

Type: boolean

Indicates whether the polygon tool should be hidden. The polygon tool allows for selecting features by drawing a polygon.

Attribute: hide-polygon-tool
Default value: false

hideProgress

Property

Type: boolean

Indicates whether the progress indicator should be hidden.

The progress indicator shows when a selection operation is processing results. The processing time can vary depending on the potential number of selected features, or whether the selection operation is querying source layers or layer views for results.

Attribute: hide-progress
Default value: false

hideRectangleTool

Property

Type: boolean

Indicates whether the rectangle selection tool is hidden. The rectangle tool allows users to select features by drawing a rectangular area.

Attribute: hide-rectangle-tool
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-set"

ignoreLayerVisibility

Property

Type: boolean

Indicates whether the selection toolbar will ignore layer visibility when determining selection results. Non-visible layers and layer views are typically excluded from selection results.

Attribute: ignore-layer-visibility
Default value: false

label

Property

Type: string | undefined

The component's default label.

Attribute: label

layerPreferenceEnabled

Property

Type: boolean

Indicates whether selection operations should always query source layers rather than their associated layer views when determining selection results. Querying the source layer may be necessary when the most up-to-date feature data is required. Changing this property while a selection operation is in progress will not affect the active operation. The change will apply only to subsequent operations.

Attribute: layer-preference-enabled
Default value: false

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

returnFeatureTitleFields

Property

Type: boolean

Determines whether selected features include the fields required to display feature titles as defined by the web map.

When enabled, these fields are available on features returned by selection events. They are not stored in the selection manager, which stores only selected feature Object IDs.

Enabling this property may require additional queries and can affect selection performance.

Attribute: return-feature-title-fields
Default value: false

returnGeometryDisabled

Property

Type: boolean

Indicates whether to omit feature geometries from features returned by selection events. Disable this property when selected feature geometries are needed by an application.

Geometries are not stored in the selection manager, which stores only selected feature Object IDs.

Disabling geometry results may improve selection performance when geometries are not needed.

Attribute: return-geometry-disabled
Default value: false

selectionManager

Property

Type: SelectionManager | null | undefined

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

When using a custom selection manager, ensure its sources include the layers and tables that should participate in a selection. Call syncSources() after adding or removing layers from the view.

sources

Property

Type: Array<SelectionSource> | null | undefined

An array of layers or layer views used to determine the selection.

state

readonly Property

Type: "active" | "disabled" | "ready"

Reflects the current operational state of the selection toolbar.

syncResultsDisabled

Property

Type: boolean

Indicates whether results from new selection operations are not automatically synchronized with the associated selection manager. When set to true, events emitted by the selection-toolbar will still include the updated selection results, but the associated selection manager will not be updated when the selection operation completes.

Attribute: sync-results-disabled
Default value: false

syncWhileDrawing

Property

Type: boolean

Indicates whether the selection operation continuously evaluates the potential selection while the associated draw tool is active and emits updates through events. When set to false, the selection is evaluated only once after drawing is complete.

Potential selection results are not stored or reflected by the associated selection manager. Set this property to true to receive continuous updates to the working selection set, such as for highlighting potential features while drawing. This property does not control whether the final selection results are stored by the selection manager; use syncResultsDisabled for that behavior.

Attribute: sync-while-drawing
Default value: false

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

visualScale

Property

Type: Action["scale"]

Controls the scale of any rendered Calcite elements.

Attribute: visual-scale
Default value: "m"

Methods

Method	Signature
activate	activate(options?: SelectionOperationProperties): Promise<SelectionOperation \| undefined>
activateTool	activateTool(toolName: SelectionToolName): Promise<SelectionOperation \| undefined>
cancel	cancel(): Promise<void>
componentOnReady inherited	componentOnReady(): Promise<this>
destroy	destroy(): Promise<void>
syncSources	syncSources(): Promise<void>
toggleTool	toggleTool(toolName: SelectionToolName): Promise<SelectionOperation \| undefined>

activate

Method

Signature: activate (options?: SelectionOperationProperties): Promise<SelectionOperation | undefined>

Activates the specified tool using the provided options and cancels any active selection operation. This method has no effect when the toolbar is disabled.

Parameters

Parameter	Type	Description	Required
options	SelectionOperationProperties	Optional tool and operation configuration.

Returns: Promise<SelectionOperation | undefined>
A promise that resolves to the active selection operation, or undefined if activation was blocked.

Example

// Once the selection-toolbar is ready, activate the lasso tool and "replace" operation type

const viewElement = document.querySelector("arcgis-map");
const selectionToolbar = document.querySelector("arcgis-selection-toolbar");
await viewElement.viewOnReady();
await selectionToolbar.componentOnReady();
await selectionToolbar.activate({
  toolName: "lasso",
  type: "replace"
});

activateTool

Method

Signature: activateTool (toolName: SelectionToolName): Promise<SelectionOperation | undefined>

Activates the specified tool by name and cancels any selection operation. This method has no effect when the toolbar is disabled.

Parameters

Parameter	Type	Description	Required
toolName	SelectionToolName	The name of the tool to activate.

Returns: Promise<SelectionOperation | undefined>
A promise that resolves to the active selection operation, or undefined if activation was blocked.

Example

// Once the selection-toolbar is ready, activate the rectangle tool

const viewElement = document.querySelector("arcgis-map");
const selectionToolbar = document.querySelector("arcgis-selection-toolbar");
await viewElement.viewOnReady();
await selectionToolbar.componentOnReady();
await selectionToolbar.activateTool("rectangle");

cancel

Method

Signature: cancel (): Promise<void>

Cancels any active operation and, when applicable, emits a complete event. The event includes an aborted property that indicates whether the operation was canceled.

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

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroy the component.

Returns: Promise<void>

syncSources

Method

Signature: syncSources (): Promise<void>

Synchronizes the effective selection manager with the current layers and tables in the view.

Call this method after adding or removing layers or tables from the view, especially when using a custom selection manager. Newly added sources are otherwise excluded from selection results.

This method has no effect if the effective selection manager does not have an assigned view.

Returns: Promise<void>

toggleTool

Method

Signature: toggleTool (toolName: SelectionToolName): Promise<SelectionOperation | undefined>

Toggles the active state of the specified tool. If the tool is currently active, it is canceled. Otherwise, the tool is activated after canceling any active selection operation.

Parameters

Parameter	Type	Description	Required
toolName	SelectionToolName	The name of the tool to toggle.

Returns: Promise<SelectionOperation | undefined>
A promise that resolves to the active selection operation if the associated tool was toggled on, or undefined if the tool was toggled off.

Events

Name	Type
arcgisBeforeActivate	CustomEvent<SelectionToolbarViewModelEvents["before-activate"]>
arcgisClear	CustomEvent<void>
arcgisComplete	CustomEvent<SelectionToolbarViewModelEvents["complete"]>
arcgisPropertyChange	CustomEvent<{ name: "activeOperation" \| "state"; }>
arcgisReady	CustomEvent<void>
arcgisSelectionChange	CustomEvent<SelectionToolbarViewModelEvents["selection-change"]>

arcgisBeforeActivate

Event

arcgisBeforeActivate: CustomEvent<SelectionToolbarViewModelEvents["before-activate"]>

Fires before any selection operation is activated.

Example

const toolbar = document.querySelector("arcgis-selection-toolbar");
toolbar.addEventListener("arcgisBeforeActivate", (event) => {
  const { toolName } = event.detail.detail;
  console.log("Starting selection tool:", toolName);
});

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.

arcgisComplete

Event

arcgisComplete: CustomEvent<SelectionToolbarViewModelEvents["complete"]>

Fires when the selection operation is complete or canceled and results have been processed.

Example

const toolbar = document.querySelector("arcgis-selection-toolbar");
toolbar.addEventListener("arcgisComplete", (event) => {
  const { aborted, selection, operationType, toolName } = event.detail;
  console.log("Selection complete:", {
    aborted,
    selection,
    operationType,
    toolName
  });
});

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "activeOperation" | "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.

arcgisSelectionChange

Event

arcgisSelectionChange: CustomEvent<SelectionToolbarViewModelEvents["selection-change"]>

Fires when the potential selection set changes while drawing. This event will not fire unless the syncWhileDrawing property is set to true. For the final selection set, use the complete event or refer to the associated selection manager.

Example

const toolbar = document.querySelector("arcgis-selection-toolbar");
toolbar.addEventListener("arcgisSelectionChange", (event) => {
  const { added, removed, operationType } = event.detail;
  console.log("Selection changed:", {
    added,
    removed,
    operationType,
  });
});