arcgis-value-picker | References | ArcGIS Maps SDK for JavaScript

ESM

import "@arcgis/common-components/components/arcgis-value-picker";

Inheritance: ArcgisValuePicker→HTMLElement

Since: ArcGIS Maps SDK for JavaScript 5.2

The Value Picker component allows users to step or play through an iterable set of data. The component alone acts as a shell, consisting of a play/pause button, a next button, a previous button, and a slot for adding a component to Value Picker. Value Picker is not associated with a View nor does it require that the dataset adheres to a specific structure for it to function.

The arcgis-value-picker-label, arcgis-value-picker-slider, arcgis-value-picker-combobox, and arcgis-value-picker-collection components provide the user with a few different options for placing their data into a Value Picker with minimal configuration. Value Picker handles the different shapes of these components automatically by asserting that all slotted components will extend the ArcgisValuePickerSubcomponent interface, which allows Value picker to send and receive generic sets of instructions that are interpreted by the slotted component.

Configuring Value Picker

Configuring Value Picker without slotted components

value-picker-nodata

<arcgis-map itemId="462c629e8e604c15baf45627c4f337d6">
  <arcgis-value-picker slot="top-right"></arcgis-value-picker>
</arcgis-map>

If a user wishes to use Value Picker with a component or dataset that can't be accurately represented by the slottable components, the component may be placed adjacent to the empty Value Picker, and events fired by Value Picker can be used to orchestrate the behavior of the adjacent component. For example, when the user clicks the play button, Value Picker will emit @arcgisAnimate each time playRate ms have elapsed since the button was clicked, which the user could listen to and iterate the index of their dataset on an interval as a result.

const valuePicker = document.querySelector("arcgis-value-picker");
const basemapGallery = document.querySelector("arcgis-basemap-gallery");

const basemaps = new Collection([
  Basemap.fromId("topo-vector"),
  Basemap.fromId("hybrid"),
  Basemap.fromId("streets"),
  Basemap.fromId("satellite"),
  Basemap.fromId("oceans"),
]);

basemapGallery.source = new LocalBasemapsSource({ basemaps });
basemapGallery.activeBasemap = basemaps.getItemAt(0);

valuePicker.addEventListener("arcgisAnimate", () => {
  const currentIndex = basemaps.indexOf(basemapGallery.activeBasemap);
  basemapGallery.activeBasemap = basemaps.getItemAt(currentIndex + 1);
});

Configuring Value Picker with slotted components

A single component may be placed into the Value Picker slot by placing one element inside of the other:

<arcgis-value-picker>
  <arcgis-value-picker-slider></arcgis-value-picker-slider>
</arcgis-value-picker>

1. Using a label component to step through a list of items

Consider using the arcgis-value-picker-label component to step through a small, fixed list of predefined values. This component provides a strict interface that steps back and forth, so it's a good option for temporal data, or data that shows progression dependent on the element's position in the list.

value-picker-label

const mapElement = document.querySelector("arcgis-map");
const valuePickerLabel = document.querySelector("arcgis-value-picker-label");

const labelItems = [
  { value: "2017", label: "Tree cover in 2017" },
  { value: "2018", label: "Tree cover in 2018" },
  { value: "2019", label: "Tree cover in 2019" },
  { value: "2020", label: "Tree cover in 2020" },
  { value: "2021", label: "Tree cover in 2021" }
];

valuePickerLabel.items = labelItems;

valuePickerLabel.currentValue = labelItems[0];

The user's interaction can be handled by monitoring the arcgis-value-picker-label.currentValue property.

valuePickerLabel.addEventListener("arcgisPropertyChange", () => {
  const year = Number(valuePickerLabel.currentValue.value);
  mapElement.view.timeExtent = {
    start: new Date(year, 0, 1),
    end: new Date(year + 1, 0, 1),
  };
  console.log("The current year is: ", valuePickerLabel.currentValue.value);
});

2. Using a slider component to traverse a list of items

Consider using the arcgis-value-picker-slider component to quickly traverse through a set of data that can be represented along a fixed numeric range. This is a good option for sets of elements spaced along an interval, or mutating a continuous parameter such as layer opacity.

value-picker-slider

const valuePickerSlider = document.querySelector("arcgis-value-picker-slider");

valuePickerSlider.steps = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
valuePickerSlider.labels = [0, 20, 40, 60, 80, 100];
valuePickerSlider.majorTicks = [0, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
valuePickerSlider.minorTicks = [5, 15, 25, 35, 45, 55, 65, 75, 85, 95];
valuePickerSlider.currentValue = 100;
valuePickerSlider.labelFormatter = (value) => `${value}%`;

The user's interaction can be handled by monitoring the arcgis-value-picker-slider.currentValue property.

valuePickerSlider.addEventListener("arcgisPropertyChange", () => {
  layer.opacity = valuePickerSlider.currentValue / 100;
  console.log("The current layer opacity is: ", valuePickerSlider.currentValue / 100);
});

Note that arcgis-value-picker-slider.labels, arcgis-value-picker-slider.majorTicks, and arcgis-value-picker-slider.minorTicks are all independent of each other and optional.

3. Using a combobox component to select from a list of items

Consider using the arcgis-value-picker-combobox component to step through a longer list of items that cannot be clicked through one by one. The combobox component allows the user to open the list as a dropdown and make a selection, or narrow the size of the list by searching for an element or keyword.

value-picker-combobox

const valuePickerCombobox = document.querySelector("arcgis-value-picker-combobox");

const comboboxItems = [
  { value: "Bare", label: "Isolate Bare Ground Areas" },
  { value: "Built", label: "Isolate Built Areas" },
  { value: "Trees", label: "Isolate Trees" },
  { value: "Water", label: "Isolate Water Areas" },
  { value: "Crops", label: "Isolate Crop Areas" },
];

valuePickerCombobox.items = comboboxItems;

valuePickerCombobox.currentValue = comboboxItems[0];

The user's interaction can be handled by monitoring the arcgis-value-picker-combobox.currentValue property.

valuePickerCombobox.addEventListener("arcgisPropertyChange", () => {
  layer.rasterFunction = {
    functionName: valuePickerCombobox.currentValue.value,
  };
  console.log("The current land cover category is: ", valuePickerCombobox.currentValue.value);
});

4. Using a collection component to step through an arbitrary set of data

Consider using the arcgis-value-picker-collection component when a visual representation for the dataset is not necessary. This is also a good option for datasets already in the form of a Collection.

value-picker-collection

const Collection = (await import("@arcgis/core/core/Collection.js")).default;

const mapElement = document.querySelector("arcgis-map");
const valuePickerCollection = document.querySelector("arcgis-value-picker-collection");

const basemapCollection = new Collection(["topo-vector", "streets", "osm"]);

valuePickerCollection.items = basemapCollection;

valuePickerCollection.currentValue = "topo-vector";

The user's interaction can be handled by monitoring the arcgis-value-picker-collection.currentValue property.

valuePickerCollection.addEventListener("arcgisPropertyChange", () => {
  mapElement.basemap = valuePickerCollection.currentValue;
  console.log("The current basemap is: ", valuePickerCollection.currentValue);
});

Demo

Properties

Property	Attribute	Type
autoDestroyDisabled	auto-destroy-disabled	boolean
disabled	disabled	boolean
floating reflected	floating	boolean
hideNextButton	hide-next-button	boolean
hidePlayButton	hide-play-button	boolean
hidePreviousButton	hide-previous-button	boolean
icon	icon	IconName
label	label	string \| undefined
layout reflected	layout	Layout
loop	loop	boolean
playRate	play-rate	number
state readonly		"playing" \| "ready"

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

disabled

Property

Type: boolean

When true, the component is visually withdrawn and cannot be interacted with. If the slotted component also has a disabled property, it will be kept in sync with this property.

Attribute: disabled
Default value: false

floating

reflected Property

Type: boolean

When set to true, the component will appear with rounded corners and a dropshadow.

Attribute: floating
Default value: false

hideNextButton

Property

Type: boolean

When set to true, the next button is not displayed.

Attribute: hide-next-button
Default value: false

hidePlayButton

Property

Type: boolean

When set to true, the play/pause button is not displayed.

Attribute: hide-play-button
Default value: false

hidePreviousButton

Property

Type: boolean

When set to true, the previous button is not displayed.

Attribute: hide-previous-button
Default value: false

icon

Property

Type: IconName

Icon which represents the component.

Attribute: icon
Default value: "list-rectangle"

label

Property

Type: string | undefined

The component's default label.

Attribute: label
Default value: ""

layout

reflected Property

Type: Layout

Indicates the axis that the Value Picker buttons should be oriented along.

Horizontal layouts are best for wider components that don't require a lot of vertical space, or components that iterate from left to right over a dataset. Some examples of these are horizontal sliders, collapsable dropdowns, or label components.

Vertical layouts are best for taller components or components that should iterate vertically. Some examples include vertical sliders or list components that require a larger space to allow the user to scroll through the list.

Attribute: layout
Default value: "horizontal"

loop

Property

Type: boolean

When set to true, playback will restart from the first element of the slotted component's dataset once it reaches the end. Note that this will not allow the Value Picker buttons to be used to manually loop back to the first element.

Attribute: loop
Default value: false

playRate

Property

Type: number

Specifies the interval, in milliseconds, on which the component will call step("next") on the slotted component.

Attribute: play-rate
Default value: 1000

state

readonly Property

Type: "playing" | "ready"

The current state of the component.

Methods

Method	Signature
componentOnReady inherited	componentOnReady(): Promise<this>
destroy	destroy(): Promise<void>
next	next(): void
pause	pause(): void
play	play(): void
previous	previous(): void

componentOnReady

inherited Method

Signature: componentOnReady (): Promise<this>

Creates a promise that resolves once the component is fully loaded.

Returns: Promise<this>

Example

const arcgisValuePicker = document.createElement("arcgis-value-picker");
document.body.append(arcgisValuePicker);
await arcgisValuePicker.componentOnReady();
console.log("arcgis-value-picker is ready to go!");

destroy

Method

Signature: destroy (): Promise<void>

Permanently destroys the component.

Returns: Promise<void>

Method

Signature: next (): void

Selects the next index from the slotted component's dataset.

Returns: void

Example

const valuePicker = document.querySelector("arcgis-value-picker");
const valuePickerSlider = document.querySelector("arcgis-value-picker-slider");

valuePickerSlider.steps = [1, 2, 3, 4, 5];
valuePickerSlider.currentValue = 1;

console.log(`Current value: ${valuePickerSlider.currentValue}`); // "Current value: 1"
valuePicker.next();
console.log(`Current value: ${valuePickerSlider.currentValue}`); // "Current value: 2"

pause

Method

Signature: pause (): void

Stops the component from playing.

Returns: void

play

Method

Signature: play (): void

Start playing. Value Picker will call step("next") on the slotted component at an interval defined by playRate.

Returns: void

Example

// Start a continuously looping ValuePicker.
const valuePicker = document.querySelector("arcgis-value-picker");
const valuePickerSlider = document.querySelector("arcgis-value-picker-slider");

valuePickerSlider.steps = [1, 2, 3];
valuePickerSlider.currentValue = 1;
valuePicker.loop = true;

valuePickerSlider.addEventListener("arcgisPropertyChange", () => {
  console.log(valuePickerSlider.currentValue);
});

valuePicker.play();
// output: 1, 2, 3, 1, 2, 3, 1...

Method

Signature: previous (): void

Selects the previous index from the slotted component's dataset.

Returns: void

Example

const valuePicker = document.querySelector("arcgis-value-picker");
const valuePickerSlider = document.querySelector("arcgis-value-picker-slider");

valuePickerSlider.steps = [1, 2, 3, 4, 5];
valuePickerSlider.currentValue = 3;

console.log(`Current value: ${valuePickerSlider.currentValue}`); // "Current value: 3"
valuePicker.previous();
console.log(`Current value: ${valuePickerSlider.currentValue}`); // "Current value: 2"

Events

Name	Type
arcgisAnimate	CustomEvent<AnimateEvent>
arcgisNext	CustomEvent<void>
arcgisPause	CustomEvent<void>
arcgisPlay	CustomEvent<void>
arcgisPrevious	CustomEvent<void>
arcgisPropertyChange	CustomEvent<{ name: "layout" \| "loop" \| "playRate" \| "state"; }>
arcgisSlottedElementChange	CustomEvent<{ slottedElement: ArcgisValuePickerSubcomponent \| undefined; }>

arcgisAnimate

Event

arcgisAnimate: CustomEvent<AnimateEvent>

Fires on each playback tick after the user presses the play button. The event payload contains { first: boolean } and fires for the first time after playRate ms have elapsed since the user pressed the play button. Users should listen to this event to manually iterate an external dataset on an interval.

arcgisNext

Event

arcgisNext: CustomEvent<void>

Fires when the Value Picker's next button is pressed or when the next() method is invoked.

arcgisPause

Event

arcgisPause: CustomEvent<void>

Fires when the Value Picker's pause button is pressed or when the pause() method is invoked.

arcgisPlay

Event

arcgisPlay: CustomEvent<void>

Fires when the Value Picker's play button is pressed or when the play() method is invoked.

arcgisPrevious

Event

arcgisPrevious: CustomEvent<void>

Fires when the Value Picker's previous button is pressed or when the previous() method is invoked.

arcgisPropertyChange

Event

arcgisPropertyChange: CustomEvent<{ name: "layout" | "loop" | "playRate" | "state"; }>

arcgisSlottedElementChange

Event

arcgisSlottedElementChange: CustomEvent<{ slottedElement: ArcgisValuePickerSubcomponent | undefined; }>

Fires when the contents of Value Picker's slot changes.

Slots

Name	Description
default (unnamed)	Default slot for adding a component to value-picker. User is responsible for positioning the content via CSS.

default (unnamed)

Slot

Default slot for adding a component to value-picker. User is responsible for positioning the content via CSS.