import Collection from "@arcgis/core/core/Collection.js";
Inheritance:
CollectionAccessor
Subclasses:
SceneModifications
Since
ArcGIS Maps SDK for JavaScript 4.0

Collection stores an array of items of the same type. It provides useful utility methods for working with items in the Collection, including filter(), find(), and reduce().

A Collection can be of any type. For example, GraphicsLayer.graphics is a collection of graphics that are stored in the GraphicsLayer. You can use the methods found in the Collection class to add, remove, re-order, or manipulate graphics in a GraphicsLayer.

Another example of a Collection is Map.layers, which is a Collection of operational layers included in the Map.

// Removes a layer from the map using Collection.remove();
map.layers.remove(layer);

The change event fires each time an item is added, moved, or removed from the Collection.

As of version 4.18, you can iterate through the items of a Collection using for...of.

// a collection of graphics displayed in the view
const graphics = view.graphics;
for (const graphic of graphics){
// do something with each view graphic
}

As of version 4.23, reactiveUtils can be utilized to watch for property changes on items in a Collection.

// reactiveUtils watch method can be used to watch the visible
// property of each layer within the map.allLayer's collection
const handle = reactiveUtils.watch(
() => view.map.allLayers.every((layer) => layer.visible),
(allVisible) => {
console.log(`All layers are visible = ${allVisible}`);
}
);
See also

Constructors

Constructor

Constructor
Parameters
ParameterTypeDescriptionRequired
items

A collection of items to initialize the Collection with.

See the properties table for a list of all the properties that may be passed into the constructor.

Properties

Any properties can be set, retrieved or listened to. See the Watch for changes topic.
PropertyTypeClass
declaredClass
readonly inherited

declaredClass

readonlyinherited Property
Type
string
Inherited from: Accessor
Since
ArcGIS Maps SDK for JavaScript 4.7

The name of the class. The declared class name is formatted as esri.folder.className.

length

Property
Type
number

The number of items in the Collection. Like a native Array, setting the length of a Collection can be used to remove items from the end of the collection. However, unlike a native Array, you cannot increase the length of the collection to reserve space for new items.

Methods

MethodSignatureClass
isCollection
static
isCollection<T>(value: T): value is Extract<T, Collection<unknown>>
ofType
static
ofType<T extends Base, Base = T>(type: (new (...args: any[]) => T) | Types<T, Base>): new (items?: ReadonlyArrayOrCollection<T> | { items?: ReadonlyArrayOrCollection<T>; }) => Collection<T>
[Symbol.iterator](): IterableIterator<T>
add
add(item: T, index?: number): this
addMany(items: ReadonlyArrayOrCollection<T>, index?: number): this
at
at(index: number): T | undefined
clone(): Collection<T>
concat(value: ReadonlyArrayOrCollection<T>): Collection<T>
destroyAll(): void
destroyMany(items: ReadonlyArrayOrCollection<T>): T[]
drain(callback: ItemCallback<T>, thisArg?: any): void
emit
inherited
emit<Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
every(callback: ItemTestCallback<T>, thisArg?: any): boolean
filter<S extends T>(callback: (item: T, index: number, array: T[]) => item is S, thisArg?: any): Collection<S>
filter(callback: ItemTestCallback<T>, thisArg?: any): Collection<T>
find(callback: ItemTestCallback<T>, thisArg?: any): T | undefined
findIndex(callback: ItemTestCallback<T>, thisArg?: any): number
flatten(callback: ItemFlattenCallback<T>, thisArg?: any): Collection<T>
flatten<U>(callback: ItemFlattenCallback<U>, thisArg?: any): Collection<U>
forEach(callback: ItemCallback<T>, thisArg?: any): void
getItemAt(index: number): T | undefined
hasEventListener
inherited
hasEventListener<Type extends EventNames<this>>(type: Type): boolean
includes(searchElement: T): boolean
indexOf(searchElement: T, fromIndex?: number): number
join(separator?: string): string
lastIndexOf(searchElement: T, fromIndex?: number): number
map
map<TRet>(callback: ItemMapCallback<T, TRet>, thisArg?: any): Collection<TRet>
on
inherited
on<Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
pop
pop(): T | undefined
push(...items: T[]): number
reduce<R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R
reduceRight<R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R
remove(item: T): T | undefined
removeAll(): T[]
removeAt(index: number): T | undefined
removeMany(items: ReadonlyArrayOrCollection<T>): T[]
reorder(item: T, index?: number): T | undefined
reverse(): this
shift(): T | undefined
slice(begin?: number, end?: number): Collection<T>
some(callback: (item: T, index: number, array: T[]) => boolean, thisArg?: any): boolean
sort(compareFunction?: ItemCompareCallback<T>): this
splice(start: number, deleteCount?: number, ...items: T[]): T[]
toArray(): T[]
toString(): string
unshift(...items: T[]): number

isCollection

static Method
Signature
isCollection <T>(value: T): value is Extract<T, Collection<unknown>>
Type parameters
<T>

Determines whether the passed value is a Collection.

Parameters
ParameterTypeDescriptionRequired
value
T

The value to be checked.

Returns
value is Extract<T, Collection<unknown>>

true if the test passes, false otherwise.

ofType

static Method
Signature
ofType <T extends Base, Base = T>(type: (new (...args: any[]) => T) | Types<T, Base>): new (items?: ReadonlyArrayOrCollection<T> | { items?: ReadonlyArrayOrCollection<T>; }) => Collection<T>
Type parameters
<T extends Base, Base = T>

Creates a subclass of Collection containing a typed object.

Parameters
ParameterTypeDescriptionRequired
type
(new (...args: any[]) => T) | Types<T, Base>

The type to assign the Collection.

Returns
new (items?: ReadonlyArrayOrCollection | { items?: ReadonlyArrayOrCollection; }) => Collection

The typed collection.

Example
const [Collection, Point] = await $arcgis.import([
"@arcgis/core/core/Collection.js",
"@arcgis/core/geometry/Point.js"
]);
let PointCollection = Collection.ofType(Point);
let collection = new PointCollection();
collection.add([-100,40]);
let point = collection.at(0);
// point.x = -100; point.y = 40
});

[Symbol.iterator]

Method
Signature
[Symbol.iterator] (): IterableIterator<T>
Returns
IterableIterator

add

Method
Signature
add (item: T, index?: number): this

Adds a single item to the collection. The change event is fired after an item is added to the Collection.

Parameters
ParameterTypeDescriptionRequired
item
T

The item to add.

index

Zero-based index of where in the collection to add the item. If not specified, the items will be added at the end.

Returns
this
Example
let gpc = new Graphic(); // Creates a new graphic
let layer = new GraphicsLayer(); // Creates a new graphics layer
layer.graphics.add(gpc); // Adds graphic to layer's graphics collection

addMany

Method
Signature
addMany (items: ReadonlyArrayOrCollection<T>, index?: number): this

Adds multiple items to the collection. The change event is fired after items are added to the Collection.

Parameters
ParameterTypeDescriptionRequired
items

An array or collection of items to add.

index

Zero-based index of where in the collection to add the items. If not specified, the items will be added at the end.

Returns
this
Example
// Creates two new graphics
let gpc1 = new Graphic();
let gpc2 = new Graphic();
let layer = new GraphicsLayer(); // Creates a new graphics layer
// Adds both graphics to layer's graphics collection
layer.graphics.addMany([gpc1, gpc2]);

at

Method
Signature
at (index: number): T | undefined
Since
ArcGIS Maps SDK for JavaScript 4.23

Returns the item at the specified index, allowing for positive and negative integers. Negative integers count back from the last item in the array.

See also
Parameters
ParameterTypeDescriptionRequired
index

Index of the item in the Collection to retrieve. It can be a relative index from the end of the Collection.

Returns
T | undefined

The item in the Collection stored at the specified index.

Example
// get the layer at the first position
let firstLayer = map.layers.at(0);
// get the layer at the last position
let lastLayer = map.layers.at(-1);

clone

Method
Signature
clone (): Collection<T>

Creates a deep clone of the Collection. To create a shallow clone of the collection, use slice().

See also
Returns
Collection

A clone of the Collection that invoked this method.

Example
// slides is a clone of the scene slides
let slides = scene.presentation.slides.clone();

concat

Method
Signature
concat (value: ReadonlyArrayOrCollection<T>): Collection<T>

Creates a new Collection containing the items in the original Collection joined with the items in the input array or Collection.

See also
Parameters
ParameterTypeDescriptionRequired
value

The array or Collection to append to the existing Collection.

Returns
Collection

A new Collection comprised of the items in the Collection that invoked this method combined with the input items.

Example
// creating a collection of all the basemap's layers.
let basemap = map.basemap;
let basemapLayers = basemap.baseLayers.concat(basemap.referenceLayers);

destroyAll

Method
Signature
destroyAll (): void
Since
ArcGIS Maps SDK for JavaScript 4.30

Removes and destroys instances of all the items of the Collection.

Returns
void

destroyMany

Method
Signature
destroyMany (items: ReadonlyArrayOrCollection<T>): T[]
Since
ArcGIS Maps SDK for JavaScript 4.30

Removes each item in the input array and destroys it. If an item is present multiple times in the collection, only the first occurrence is removed and destroyed. The change event is fired after an item is removed from the Collection.

Parameters
ParameterTypeDescriptionRequired
items

The items to remove and destroy.

Returns
T[]

The removed and destroyed items present in the collection.

drain

Method
Signature
drain (callback: ItemCallback<T>, thisArg?: any): void
Since
ArcGIS Maps SDK for JavaScript 4.33

Removes all the items of the Collection and executes the input function for each item.

Parameters
ParameterTypeDescriptionRequired
callback

The function to call for each item in the Collection.

thisArg
any

Value to use as this when executing callback.

Returns
void

emit

inherited Method
Signature
emit <Type extends EventNames<this>>(type: Type, event?: this["@eventTypes"][Type]): boolean
Type parameters
<Type extends EventNames<this>>
Inherited from: EventedMixin
Since
ArcGIS Maps SDK for JavaScript 4.5

Emits an event on the instance. This method should only be used when creating subclasses of this class.

Parameters
ParameterTypeDescriptionRequired
type
Type

The name of the event.

event
this["@eventTypes"][Type]

The event payload.

Returns
boolean

true if a listener was notified

every

Method
Signature
every (callback: ItemTestCallback<T>, thisArg?: any): boolean

Determines whether all items in the Collection pass a test defined by callback. Each item in the Collection is passed into the callback until one returns a value of false.

See also
Parameters
ParameterTypeDescriptionRequired
callback

The function to call for each item in the Collection.

thisArg
any

Value to use as this when executing callback.

Returns
boolean

Returns true if every call to the callback function returned true. Returns false if at least one call to the callback returned false.

Example
let meetsStandardSize = graphicsLayer.graphics.every(function(item, i){
// Tests each geometry's area to see if it is greater than 1,000 acres
return calculateArea(item.geometry) > 1000;
});

filter

Method
Signature
filter <S extends T>(callback: (item: T, index: number, array: T[]) => item is S, thisArg?: any): Collection<S>
Type parameters
<S extends T>

Filters the Collection's items based on a test defined by the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

See also
Parameters
ParameterTypeDescriptionRequired
callback
(item: T, index: number, array: T[]) => item is S

The function that defines a test for determining whether to return the item in a new Collection.

thisArg
any

Value to use as this when executing callback.

Returns
Collection

Returns a new Collection containing the items that passed the filter test.

Example
// filteredLayers is a Collection of all the non-visible layers in the map
let filteredLayers = map.layers.filter(function(layer){
return !layer.visible;
});

filter

Method
Signature
filter (callback: ItemTestCallback<T>, thisArg?: any): Collection<T>

Filters the Collection's items based on a test defined by the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

See also
Parameters
ParameterTypeDescriptionRequired
callback

The function that defines a test for determining whether to return the item in a new Collection.

thisArg
any

Value to use as this when executing callback.

Returns
Collection

Returns a new Collection containing the items that passed the filter test.

Example
// filteredLayers is a Collection of all the non-visible layers in the map
let filteredLayers = map.layers.filter(function(layer){
return !layer.visible;
});

find

Method
Signature
find (callback: ItemTestCallback<T>, thisArg?: any): T | undefined

Returns an item in the Collection if that item passes a test as defined in the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

See also
Parameters
ParameterTypeDescriptionRequired
callback

The testing function that will assess each item in the Collection. Returns true if an item passes the test and false if it fails.

thisArg
any

Value to use as this when executing callback.

Returns
T | undefined

The first item in the Collection that satisfies the test function.

Example
// If the id of a map layer is already known, get the layer that matches the id
let myLayer = map.layers.find(function(layer){
return layer.id === "speciesLyr01";
});
// myLayer references the layer in map with ID "speciesLyr01"

findIndex

Method
Signature
findIndex (callback: ItemTestCallback<T>, thisArg?: any): number

Returns the index of an item in the Collection if that item passes a test as defined in the callback function. Each item is passed into the callback function, which returns true if the item passes the test and false if it does not.

See also
Parameters
ParameterTypeDescriptionRequired
callback

The testing function that will assess each item in the Collection. Returns true if an item passes the test and false if it fails.

thisArg
any

Value to use as this when executing callback.

Returns
number

Returns the index of the Collection item that satisfies the test function. If an item fails the test, -1 is returned.

Example
// gpcIndex is assigned the index of the first graphic whose name
// property is 'Redlands'. This result can be used in getItemAt()
let gpcIndex = graphicsLyr.graphics.findIndex(function(item){
return item.attributes.name === "Redlands";
});

flatten

Method
Signature
flatten (callback: ItemFlattenCallback<T>, thisArg?: any): Collection<T>

Flattens a hierarchical Collection containing at least one child collection. Each item in the collection is passed into the callback function, which should check for child collections specified by the developer. A flat collection of all items (parent and children) is returned.

This is useful for scenarios where the user would like to search all the layers in a map, including a GroupLayer's layers and a MapImageLayer's sublayers. The callback should return the sub-collection of the item. If multiple levels of collections exist in the hierarchy, then this method recursively executes for all sub-collections.

Parameters
ParameterTypeDescriptionRequired
callback

A function that will assess each item in the Collection.

thisArg
any

Value to use as this when executing callback.

Returns
Collection

Returns a flat collection of all items in the original collection and their children.

Example
// create a MapImageLayer with several sublayers and add to a map
// containing another GraphicsLayer
let layer = new MapImageLayer({ sublayers: [ ... ] });
let map = new Map({
layers: [ layer, new GraphicsLayer() ]
});
// A flat collection of all layers and sublayers
// (if layer is a MapImageLayer) in the map.
// This collection may be searched or used for other purposes
let allLayersAndSublayers = map.layers.flatten(function(item){
return item.layers || item.sublayers;
});

flatten

Method
Signature
flatten <U>(callback: ItemFlattenCallback<U>, thisArg?: any): Collection<U>
Type parameters
<U>

Flattens a hierarchical Collection containing at least one child collection. Each item in the collection is passed into the callback function, which should check for child collections specified by the developer. A flat collection of all items (parent and children) is returned.

This is useful for scenarios where the user would like to search all the layers in a map, including a GroupLayer's layers and a MapImageLayer's sublayers. The callback should return the sub-collection of the item. If multiple levels of collections exist in the hierarchy, then this method recursively executes for all sub-collections.

Parameters
ParameterTypeDescriptionRequired
callback

A function that will assess each item in the Collection.

thisArg
any

Value to use as this when executing callback.

Returns
Collection

Returns a flat collection of all items in the original collection and their children.

Example
// create a MapImageLayer with several sublayers and add to a map
// containing another GraphicsLayer
let layer = new MapImageLayer({ sublayers: [ ... ] });
let map = new Map({
layers: [ layer, new GraphicsLayer() ]
});
// A flat collection of all layers and sublayers
// (if layer is a MapImageLayer) in the map.
// This collection may be searched or used for other purposes
let allLayersAndSublayers = map.layers.flatten(function(item){
return item.layers || item.sublayers;
});

forEach

Method
Signature
forEach (callback: ItemCallback<T>, thisArg?: any): void

Executes the input function for each item in the Collection.

See also
Parameters
ParameterTypeDescriptionRequired
callback

The function to call for each item in the Collection.

thisArg
any

Value to use as this when executing callback.

Returns
void
Example
graphicsLayer.graphics.forEach(function(item, i){
// Do something here to each graphic like calculate area of its geometry
calculateArea(item.geometry);
});

getItemAt

Method
Signature
getItemAt (index: number): T | undefined

Returns the item at the specified index.

Parameters
ParameterTypeDescriptionRequired
index

Zero-based index of the item in the Collection to retrieve.

Returns
T | undefined

The item in the Collection stored at the specified index.

Example
// Assigns the base layer at index 0 to baseLayer
let baseLayer = map.basemap.baseLayers.getItemAt(0);

hasEventListener

inherited Method
Signature
hasEventListener <Type extends EventNames<this>>(type: Type): boolean
Type parameters
<Type extends EventNames<this>>
Inherited from: EventedMixin

Indicates whether there is an event listener on the instance that matches the provided event name.

Parameters
ParameterTypeDescriptionRequired
type
Type

The name of the event.

Returns
boolean

Returns true if the class supports the input event.

includes

Method
Signature
includes (searchElement: T): boolean

Tests if an item is present in the new Collection.

See also
Parameters
ParameterTypeDescriptionRequired
searchElement
T

The item to search for in the collection.

Returns
boolean

true if the item is in the collection.

Example
// check if a layer is in the map's operational layers.
if (view.map.layers.includes(myLayer)) {
// ...
}

indexOf

Method
Signature
indexOf (searchElement: T, fromIndex?: number): number

Returns the index of an element in the collection.

See also
Parameters
ParameterTypeDescriptionRequired
searchElement
T

Item to search for in the collection.

fromIndex

Use if you don't want to search the whole collection or you don't want to search from the start.

Returns
number

The location of the first match found in the collection, or -1 if there is no match.

Example
// index is the index of the first graphic in the
// graphics layer that matches the input graphic
let index = graphicsLayer.graphics.indexOf(graphic);

join

Method
Signature
join (separator?: string): string

Creates a string representation of the items in the Collection.

See also
Parameters
ParameterTypeDescriptionRequired
separator

= , - The separator used between each item in the final string.

Returns
string

The string representation of the items.

Example
let stringCollection = new Collection(["how", "are", "you", "doing?"]);
let phrase = stringCollection.join(" ");
// Prints "how are you doing?"
console.log(phrase);

lastIndexOf

Method
Signature
lastIndexOf (searchElement: T, fromIndex?: number): number

Returns the last index of an element in the collection.

See also
Parameters
ParameterTypeDescriptionRequired
searchElement
T

Item to search for in the collection.

fromIndex

Use if you don't want to search the whole collection, or you don't want to search from the end.

Returns
number

The location of the last match found in the collection, or -1 if there is no match.

Example
// index is the index of the first graphic in the
// graphics layer that matches the input graphic
let index = graphicsLayer.graphics.lastIndexOf(graphic);

map

Method
Signature
map <TRet>(callback: ItemMapCallback<T, TRet>, thisArg?: any): Collection<TRet>
Type parameters
<TRet>

Passes each Collection item into the callback function and returns a new array of the returned values. For example, if you have a Collection of numbers and would like to add each number by 10, you can use map() to create a new Collection with the same numbers incremented by 10.

See also
Parameters
ParameterTypeDescriptionRequired
callback
ItemMapCallback<T, TRet>

The function that processes each item in the Collection and returns a new value at the same index of the original item.

thisArg
any

Value to use as this when executing callback.

Returns
Collection

Returns a new collection containing the new items generated from the callback.

Example
// Gets the geometries of the graphics and assigns them to a new Collection
let geometries = graphicsLayer.graphics.map(function(item, i){
return item.geometry;
});

on

inherited Method
Signature
on <Type extends EventNames<this>>(type: Type, listener: EventedCallback<this["@eventTypes"][Type]>): ResourceHandle
Type parameters
<Type extends EventNames<this>>
Inherited from: EventedMixin

Registers an event handler on the instance. Call this method to hook an event with a listener.

Parameters
ParameterTypeDescriptionRequired
type
Type

An event or an array of events to listen for.

listener
EventedCallback<this["@eventTypes"][Type]>

The function to call when the event fires.

Returns
ResourceHandle

Returns an event handler with a remove() method that should be called to stop listening for the event(s).

PropertyTypeDescription
removeFunctionWhen called, removes the listener from the event.
Example
view.on("click", function(event){
// event is the event handle returned after the event fires.
console.log(event.mapPoint);
});

pop

Method
Signature
pop (): T | undefined

Removes the last item from the collection and returns it.

See also
Returns
T | undefined

The last item in the collection.

Example
// Removes the last layer in the map and stores it in lastLayer
let lastLayer = map.layers.pop();

push

Method
Signature
push (...items: T[]): number

Adds an item(s) to the end of the collection.

See also
Parameters
ParameterTypeDescriptionRequired
items
T[]

An item or comma-separated list of items to add to the end of the collection.

Returns
number

The new length of the collection.

Examples
// Adds a new graphic to the end of the graphics collection on a GraphicsLayer
graphicsLyr.graphics.push(newGraphic);
// Adds three new graphics to the end of the GraphicsLayer's graphics collection
graphicsLyr.graphics.push(g1, g2, g3);

reduce

Method
Signature
reduce <R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R
Type parameters
<R = T>

Reduces all items in the collection (from left to right) into a single variable using callback.

See also
Parameters
ParameterTypeDescriptionRequired
callback

The function that processes each item in the Collection and appends it to the previous item.

initialValue
R

Item to use as the first element to process in callback.

Returns
R

Returns the value representing the reduction of the Collection's items.

reduceRight

Method
Signature
reduceRight <R = T>(callback: ItemReduceCallback<T, R>, initialValue?: R): R
Type parameters
<R = T>

Reduces all items in the collection (from right to left) into a single variable using callback.

See also
Parameters
ParameterTypeDescriptionRequired
callback

The function that processes each item in the Collection and appends it to the previous item.

initialValue
R

Item to use as the first element to process in callback.

Returns
R

Returns the value representing the reduction of the Collection's items.

remove

Method
Signature
remove (item: T): T | undefined

Removes an item from the collection. The change event is fired after an item is removed from the Collection.

Parameters
ParameterTypeDescriptionRequired
item
T

The item to remove.

Returns
T | undefined
Example
let layer = map.layers.at(4);
// Removes the fifth layer from the map
map.layers.remove(layer);

removeAll

Method
Signature
removeAll (): T[]

Removes all items from the collection.

Returns
T[]
Example
// Removes all layers from the map
map.layers.removeAll();

removeAt

Method
Signature
removeAt (index: number): T | undefined

Removes an item from the collection at a specified index. The change event is fired after an item is removed from the Collection.

Parameters
ParameterTypeDescriptionRequired
index

The index of the item to remove.

Returns
T | undefined

The removed item if present in the collection, undefined otherwise.

Example
// Removes the layer at index 4 of the map
map.layers.removeAt(4);

removeMany

Method
Signature
removeMany (items: ReadonlyArrayOrCollection<T>): T[]

Removes each item in the input array. If an item is present multiple times in the collection, only the first occurrence is removed. The change event is fired after an item is removed from the Collection.

Parameters
ParameterTypeDescriptionRequired
items

The items to remove.

Returns
T[]

The removed items present in the collection.

Example
let refLayers = [refLyr1, refLyr2, refLyr3];
// Removes three reference layers in the refLayers
// collection from the basemap's referenceLayers
map.basemap.referenceLayers.removeMany(refLayers);

reorder

Method
Signature
reorder (item: T, index?: number): T | undefined

Moves an item in the Collection to a specified index. The change event is fired after an item is moved in the Collection.

Parameters
ParameterTypeDescriptionRequired
item
T

The item to move.

index

The index to move the item to.

Returns
T | undefined

The item that was moved. undefined if item is not in the collection

Example
// Get the first two layers in a map
let layer1 = map.layers.at(0);
let layer2 = map.layers.at(1);
// Moves the second layer to the first position in the map.layers Collection
// effectively swapping the positions of layer1 and layer2
map.layers.reorder(layer2, 0);

reverse

Method
Signature
reverse (): this

Reverses the collection in place.

See also
Returns
this

The reversed collection.

Example
// Reverse layers from the map
map.layers.reverse();

shift

Method
Signature
shift (): T | undefined

Removes the first item from the collection (at index 0), and returns it. The remaining items of the collection are then shifted down one index from their previous location.

See also
Returns
T | undefined

The first item in the collection.

Example
// Removes the first layer in the map and stores it in firstLyr
let firstLyr = map.layers.shift();

slice

Method
Signature
slice (begin?: number, end?: number): Collection<T>

Creates a new Collection comprised of a portion of the original Collection.

See also
Parameters
ParameterTypeDescriptionRequired
begin

The index of the first item to extract.

end

The index of the last item to extract.

Returns
Collection

Returns a new Collection containing the items in the specified range.

Example
// get the graphics from index 50 to 100;
let selection = graphicsLayer.graphics.slice(50, 100);

some

Method
Signature
some (callback: (item: T, index: number, array: T[]) => boolean, thisArg?: any): boolean

Determines whether an item in the Collection passes a test defined by callback. Each item in the Collection is passed into the callback until one returns a value of true.

See also
Parameters
ParameterTypeDescriptionRequired
callback
(item: T, index: number, array: T[]) => boolean

The function that defines the test for each Collection item.

thisArg
any

Value to use as this when executing callback.

Returns
boolean

Returns true if any of the items in the Collection pass the test defined in callback. Returns false if all items fail the test.

Example
// If at least one of the point graphics has a geometry whose
// elevation is above 1000m, then passes will have a value of true.
// Otherwise, it will be false.
let passes = graphicsLayer.graphics.some(function(item, i){
return item.geometry.z > 1000;
});

sort

Method
Signature
sort (compareFunction?: ItemCompareCallback<T>): this

Sorts the Collection in place.

See also
Parameters
ParameterTypeDescriptionRequired
compareFunction

The function that defines a comparison of two items in the collection.

Returns
this
Example
// Sort graphics based on their elevation or z-value
let sortedGraphics = graphicsLayer.graphics.sort(function(a, b){
if(a.geometry.z > b.geometry.z){
return 1;
}
else if (a.geometry.z < b.geometry.z){
return -1;
}
else {
return 0;
}
});

splice

Method
Signature
splice (start: number, deleteCount?: number, ...items: T[]): T[]

Removes existing items and/or adds new items to the collection.

See also
Parameters
ParameterTypeDescriptionRequired
start

Index at which to start changing the collection.

deleteCount

Indicates the number of collection items to remove. If omitted, or if greater than or equal to the number of elements after the position specified by start, then all the elements from start to the end will be deleted. If 0 or undefined is used, then no elements are removed and at least one new item should be added in the items parameter.

items
T[]

The item or comma-separated list of items to add to the collection.

Returns
T[]

An array of the deleted items formerly part of the collection.

Examples
// map.layers is a collection of 6 layers
// Adds a seventh layer to the map at index 3
map.layers.splice(3, 0, layer7);
// Removes two layers starting from index 2 and adds the
// specified layers in the positions of the former layers
let oldLayers = map.layers.splice(2, 2, layer8, layer9, layer10);
// oldLayers = [layer2, layer3]

toArray

Method
Signature
toArray (): T[]

Returns a new array object containing the Collection's items.

Returns
T[]

An array containing the Collection's items.

Example
// Creates an array populated with the map's layers
let mapLayersArray = map.layers.toArray();

toString

Method
Signature
toString (): string
Returns
string

unshift

Method
Signature
unshift (...items: T[]): number

Adds one or more items to the beginning of the collection.

See also
Parameters
ParameterTypeDescriptionRequired
items
T[]

The item(s) to add to the beginning of the collection.

Returns
number

The new length of the collection.

Example
// If a map's basemap has 3 baseLayers: baseLyr0, baseLyr1, baseLyr2
map.basemap.baseLayers.unshift(baseLyr3);
// Now the baseLayers collection is: baseLyr3, baseLyr0, baseLyr1, baseLyr2

Events

after-add

Event

Fires after an item has been added to the collection.

bubbles composed cancelable
Example
// indicates a layer has been added to the map
map.layers.on("after-add", function(event){
console.log(event.item, " has been added to the map.");
});

after-changes

Event

Fires after an item has been added, reordered or removed from the collection.

bubbles composed cancelable
Example
map.layers.on("after-changes", function(event){
console.log(event, " layer was added/removed from the map.");
});

after-remove

Event

Fires after an item has been removed from the collection.

bubbles composed cancelable
Example
// indicates a layer has been removed from the map
map.layers.on("after-remove", function(event){
console.log(event.item, " has been removed from the map.");
});

before-add

Event

Fires before an item is added to the collection. This event can be used to prevent an item from being added to the collection by cancelling it with the event.preventDefault() method.

bubbles composed cancelable
Example
// prevents a layer from being added to the map more than once.
map.layers.on("before-add", function(event){
if(map.layers.includes(event.item)){
event.preventDefault();
console.log("layer already exists in map.");
}
});

before-changes

Event

Fires before any modifications are performed on the collection. This event can be used to prevent an item from being added or removed from the collection by cancelling it with the event.preventDefault() method.

bubbles composed cancelable
Example
map.layers.on("before-changes", function(event){
// prevents layers from being added/removed from the map
event.preventDefault();
});

before-remove

Event

Fires before an item has been removed from the collection. This event can be used to prevent an item from being removed from the collection by cancelling it with the event.preventDefault() method.

bubbles composed cancelable
Example
// prevents a layer from being removed from the basemap
map.basemap.baseLayers.on("before-remove", function(event){
if(map.basemap.baseLayers.includes(event.item)){
event.preventDefault();
console.log("layer cannot be removed from basemap.");
}
});

change

Event

Fires after an item has been added, reordered, or removed from the Collection. Using methods of other classes that affect properties of type Collection will also cause this event to fire, such as Map.add(), Map.remove(), Map.reorder().

For example, map.layers.add(newLyr) and map.add(newLyr) which uses Map.add() to add a new layer to the map.layers collection will cause this event to fire.

The change event can be used to notify the developer/user of changes to the collection. The arrays in the collection event objects are reused. Make a copy of the collection event object if these objects need to be processed in your application.

bubbles composed cancelable
Example
// This function will fire each time a layer is either added,
// moved, or removed from the map.layers Collection
// make a copy of the collection event object for processing
map.layers.on("change", function(event){
const copiedEvent = JSON.parse(JSON.stringify(event));
let newLayers = copiedEvent.added; // An array of layers added to the map.layers Collection
let reorderedLayers = copiedEvent.moved; // An array of layers moved in the Collection
let removedLayers = copiedEvent.removed; // An array of layers removed from map
});

Type definitions

ReadonlyArrayOrCollection

Type definition
Type parameters
<T>
Type
readonly T[] | ReadonlyCollection

CollectionChangeEvent

Type definition
Type parameters
<T = any>
Since
ArcGIS Maps SDK for JavaScript 5.0

Event object emitted when a Collection changes. It contains arrays of added, removed, and moved items.

added

Property
Type
T[]
Since
ArcGIS Maps SDK for JavaScript 5.0

An array of items added to the collection using either add() or addMany().

removed

Property
Type
T[]
Since
ArcGIS Maps SDK for JavaScript 5.0

An array of items removed from the collection using either remove(), removeMany(), removeAt(), or removeAll().

moved

Property
Type
T[]
Since
ArcGIS Maps SDK for JavaScript 5.0

An array of items that moved in the collection using reorder().

CollectionEventObject

Type definition
Type parameters
<T>

cancellable

Property
Type
boolean

Indicates if the @change event can be cancelled.

Default value
false

defaultPrevented

Property
Type
boolean

Indicates if this event has previously been cancelled by another event handler.

Default value
false

item

Property
Type
T

The item to add or remove from the collection.

preventDefault

Method
Signature
preventDefault (): void

A method that prevents the item from being added or removed from the collection.

Returns
void

CollectionAfterItemEvent

Type definition
Type parameters
<T>

item

Property
Type
T

The item to add or remove from the collection.

CollectionAfterEvent

Type definition
Type parameters
<T>

ReadonlyCollection

Type definition
Type parameters
<T>
Supertypes
EventedMixin ‚  Pick<Collection‚ "addHandles" | "at" | "clone" | "concat" | "declaredClass" | "destroyed" | "every" | "filter" | "find" | "findIndex" | "flatten" | "forEach" | "getItemAt" | "hasHandles" | "includes" | "initialized" | "indexOf" | "join" | "lastIndexOf" | "map" | "reduce" | "reduceRight" | "removeHandles" | "slice" | "some" | "toArray" | "toString" | "watch" | typeof Symbol.iterator>

@eventTypes

readonly Property
Type
Collection["@eventTypes"]

length

readonly Property
Type
number

ItemCallback

Type definition
Type parameters
<T>

The function that is called for each Collection item.

Parameters
ParameterTypeDescriptionRequired
item
T

The current item being assessed in the collection.

index

The index of the item being assessed.

Returns
void

ItemFlattenCallback

Type definition
Type parameters
<T>
Parameters
ParameterTypeDescriptionRequired
item
T

The current item being assessed in the collection.

index

The index of the item being assessed.

Returns
T[] | Collection

ItemTestCallback

Type definition
Type parameters
<T>

The function that defines a test and is called for each Collection item.

Parameters
ParameterTypeDescriptionRequired
item
T

The current item being assessed in the collection.

index

The index of the item being assessed.

array
T[]

The entire array of items in the collection.

Returns
boolean

true if the test passes, false otherwise.

ItemMapCallback

Type definition
Type parameters
<T, TRet>

The function that defines a mapping and is called for each Collection item.

Parameters
ParameterTypeDescriptionRequired
item
T

The current item being assessed in the collection.

index

The index of the item being assessed.

Returns
TRet

the new value that replaces item.

ItemReduceCallback

Type definition
Type parameters
<T, R>

The function that defines a reducer.

Parameters
ParameterTypeDescriptionRequired
previousValue
R

The item previously reduced value.

currentValue
T

The current item being assessed in the collection.

index

The index of the item being assessed.

Returns
R

the value to be passed to the next reducer.

ItemCompareCallback

Type definition
Type parameters
<T>

The function that defines a comparison.

Parameters
ParameterTypeDescriptionRequired
firstItem
T

the first item in the comparison.

secondItem
T

the second item in the comparison.

Returns
number

-1 if firstItem is smaller than secondItem, 1 if it is larger, and 0 if both are equal.