Introduction to layers

Layers are collections of data that can be used in a Map. Layer data can be created on the client, hosted by ArcGIS Online and ArcGIS Enterprise, or hosted by external servers.

The ArcGIS Maps SDK for JavaScript has a number of layer classes that can be used to access and display data. All classes inherit from Layer. The class used depends on the format of the data and where the data is stored. Each layer type also exposes a different set of capabilities.

Below is a list of some layer classes. See Layer for the complete list.

ClassData StorageCapabilities
FeatureLayerGeographic data stored in ArcGIS Online or ArcGIS Enterprise.Displaying, querying, filtering and editing large amounts of geographic features.
GraphicsLayerGeographic data stored temporarily in memory.Displaying individual geographic features as graphics, visual aids or text on the map.
CSVLayer/KMLLayer/GeoJSONLayerGeographic or tabular data stored in an external file accessed over a network.Displaying data stored in an external file format as a layer.
TileLayer/VectorTileLayerDatasets stored in a tile scheme for fast rendering.Displaying basemaps and other tiled datasets for geographic context.
MapImageLayerGeographic data stored in ArcGIS Enterprise and rendered as an image.Displaying layers dynamically rendered by an ArcGIS Server service.
ImageryLayerGeoreferenced imagery stored in ArcGIS Enterprise.Displaying satellite or other imagery data.

Displaying data sources with a FeatureLayer

A FeatureLayer is a layer that references a collection of geographic features. All features in the collection must have the same geometry type and attribute keys.

Feature layer data sources can be either in memory from data loaded by the application or the layer will request data from a REST API service hosted on ArcGIS Online or ArcGIS Enterprise. Hosting your data in ArcGIS Online or ArcGIS Enterprise is the preferred method, especially for accessing and displaying large amounts of geographic data. Feature layers are highly optimized on both the client and the server for fast display and support a variety of other features including

ArcGIS Location Platform and ArcGIS Online provide tools for importing datasuch as GeoJSON, Excel, CSV, file geodatabases, and shapefiles. Importing data creates a feature layer item in ArcGIS Online that can be used as a server-side data source.

Client-side data sources

Typically layer data is loaded from a REST API service hosted on ArcGIS Online or ArcGIS Enterprise, however, it is also possible to create a feature layer directly from a collection of features in memory.

For example, a collection of features in Los Angeles, California, is given below in JSON format. This data can be transformed into a format acceptable for displaying in a FeatureLayer.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
  "places": [
    {
      "id": 1,
      "address": "200 N Spring St, Los Angeles, CA 90012",
      "longitude": -118.24354,
      "latitude": 34.05389
    },
    {
      "id": 2,
      "address": "419 N Fairfax Ave, Los Angeles, CA 90036",
      "longitude": -118.31966,
      "latitude": 34.13375
    }
  ]
}

The first step to create a feature layer from the above JSON data is to transform each place into a Graphic object with the attributes and geometry properties.

PropertyTypeDescription
attributesObjectKey-value pairs used to store geographical information about the feature
geometryGeometryProvides the location for a feature relative to a coordinate system. Possible values are Point, Polygon, and Polyline objects

The following code sample transforms the array of places into an array of Graphic objects.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
const graphics = places.map((place) => {
  return new Graphic({
    attributes: {
      ObjectId: place.id,
      address: place.address
    },
    geometry: {
      type: "point",
      longitude: place.longitude,
      latitude: place.latitude
    },
    symbol: {
      // autocasts as new SimpleMarkerSymbol()
      type: "simple-marker",
      color: [226, 119, 40],
      outline: {
        // autocasts as new SimpleLineSymbol()
        color: [255, 255, 255],
        width: 2
      }
    }
  });
});

The second step in creating a FeatureLayer is to actually create a FeatureLayer object, and specify at least the objectIdField, fields, renderer, and source properties described in the following table.

PropertyTypeDescription
sourceCollection<Graphic>The collection of Graphic objects used to create the feature layer
rendererRendererThe renderer used to display a symbol at the feature's location
objectIdFieldStringThe name of the field identifying the feature
fieldsObject[]An array of JavaScript objects with field names and values
popupTemplatePopupTemplateThe popup template for the feature

The following code sample creates a new FeatureLayer and explicitly sets the source property to graphics. Autocasting is used to set the renderer, popup, and fields properties.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
const featureLayer = new FeatureLayer({
  source: graphics,
  renderer: {
    type: "simple",                    // autocasts as new SimpleRenderer()
    symbol: {                          // autocasts as new SimpleMarkerSymbol()
      type: "simple-marker",
      color: "#102A44",
      outline: {                       // autocasts as new SimpleLineSymbol()
        color: "#598DD8",
        width: 2
      }
    }
  },
  popupTemplate: {                     // autocasts as new PopupTemplate()
    title: "Places in Los Angeles",
    content: [{
      type: "fields",
      fieldInfos: [
        {
          fieldName: "address",
          label: "Address",
          visible: true
        }
      ]
    }]
  },
  objectIdField: "ObjectID",           // This must be defined when creating a layer from `Graphic` objects
  fields: [
    {
      name: "ObjectID",
      alias: "ObjectID",
      type: "oid"
    },
    {
      name: "address",
      alias: "address",
      type: "string"
    }
  ]
});

map.layers.add(featureLayer);

Server-side data sources

FeatureLayer also supports collections of features returned from a a REST API service specified with by the url property. This is the most effective way to access and display large datasets. The feature layer will work with the feature service to retrieve features as efficiently as possible and, if enabled, will provide access to additional capabilities such as editing.

Use dark colors for code blocksCopy
1
2
3
4
5
var layer = new FeatureLayer({
  url: "https://services3.arcgis.com/GVgbJbqm8hXASVYi/arcgis/rest/services/Trailheads/FeatureServer/0"
});

map.layers.add(layer);

In addition to URLs you can also reference layer items stored in ArcGIS Online or ArcGIS Enterprise. These items reference a REST API service which stores the layer's data as well as additional configuration options.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
var layer = new FeatureLayer({
  portalItem: {
    id: "883cedb8c9fe4524b64d47666ed234a7",
    portal: "https://www.arcgis.com"               // Default: The ArcGIS Online Portal
  }
});

map.layers.add(layer);

Displaying graphics with a GraphicsLayer

Graphics are typically used for adding text, shapes, and images with different geometries to a map. The simplest way to create a graphics layer is to create Graphic objects as an array, and pass this array to the graphics property of a new GraphicsLayer object.

Every Graphic class includes the following properties:

PropertyTypeDescription
attributesObjectKey-value pairs used to store geographical information about features
geometryGeometryProvides the location for a feature relative to a coordinate system

Possible values are Point, Polygon, and Polyline objects
popupTemplatePopupTemplateThe popup template for the graphic
symbolSymbolDefines how the graphic will be rendered in the layer

The below code sample creates a new Graphic object with a Point geometry type, a popup, and a symbol. It then creates a new GraphicsLayer by passing an array of graphics to the graphics property.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
var pointGraphic = new Graphic({
  attributes: {
    name: "LA City Hall",
    address: "200 N Spring St, Los Angeles, CA 90012"
  },
  geometry: {
    type: "point",                     // autocasts as new Point()
    longitude: -118.24354,
    latitude: 34.05389
  },
  symbol: {
    type: "simple-marker",             // autocasts as new SimpleMarkerSymbol()
    color: [ 226, 119, 40 ],
    outline: {                         // autocasts as SimpleLineSymbol()
      color: [ 255, 255, 255 ],
      width: 2
    }
  },
  popupTemplate: {                     // autocasts as new PopupTemplate()
    title: "Places in Los Angeles",
    content: [{
      type: "fields",
      fieldInfos: [
        {
          fieldName: "name",
          label: "Name",
          visible: true
        },
        {
          fieldName: "address",
          label: "Address",
          visible: true
        }
      ]
    }]
  },
});

var graphicsLayer = new GraphicsLayer({
  graphics: [ pointGraphic ]
});

map.layers.add(graphicsLayer);

Working with external data sources

Additional types of data and files are directly supported by specific subclasses of Layer. These include specific types of layers for working with external files like CSV or GeoJSON files or integrating external services such as Bing Maps.

Layer SubclassData SourceData TypesFeaturesLimitations
CSVLayerCSV files- Vector graphics downloaded as pointsClient-side processing, popup templates, renderers with 2D and 3D symbolsMay require large download depending on the number of features
GeoRSSLayerGeoRSS feedVector graphics as points, polylines, and polygons- Graphics storage
- Popup templates
- No 3D support
- No support for renderers
GeoJSONLayerGeoJSON fileVector graphics as points, polylines, and polygonsCreate layer from GeoJSON data- Each GeoJSON Layer accepts a single geometry type
- Data must comply with RFC 7946 specification
KMLLayerKML data sourceN/AN/AN/A
OGCFeatureLayerOGC API - FeaturesPoints, polylines, polygonsRenderers, labels, popupsData must comply with the RFC 7946 specification which states that the coordinates are in SpatialReference WGS84
WFSLayer- WFS Service
Portal Item
Points, multipoints, polylines, polygonsRenderers, labels, popupsData must be GeoJSON format, only version 2.0.0 is supported.
WMSLayer- WMS Service
Portal Item
Raster data exported as a single imageOGC specificationN/A
WMTSLayer- WMTS tile services
- Portal Item
Image tilesOGC specificationN/A
OpenStreetMapLayerOpenStreetMap tile servicesImage tilesDisplays OpenStreetMap tiled contentN/A
BingMapsLayerBing Spatial Data Service dataN/AN/AN/A

Each of these layers requires different properties depending on how they are initialized. Refer to each layer type for more details. An example of creating a CSVLayer layer is shown below.

Use dark colors for code blocksCopy
1
2
3
4
5
6
7
8
var earthquakesLayer = new CSVLayer({
  url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/2.5_week.csv",
  copyright: "USGS Earthquakes",
  latitudeField: "latitude", // Defaults to "latitude"
  longitudeField: "longitude" // Defaults to "longitude"
});

map.layers.add(earthquakesLayer)

Using basemaps and tile layers

Basemaps are used to provide geographic context to a map by displaying roads, boundaries, buildings and other data. Basemaps are often served as tiles for faster rendering. Raster basemaps request pre-created images. Vector basemaps request data in a compressed binary format and style it on the client. The ArcGIS contains a curated set of basemaps.

Vector basemaps can be customized with the the Vector Tile Style Editor. Custom data can also be published as vector or raster tiles with ArcGIS Online or ArcGIS Enterprise.

The basemap for a specific Map object can be controlled with the basemap property which can be a string identifying a specific basemap or a Basemap object.

Use dark colors for code blocksCopy
1
2
3
var Map = new Map({
  basemap: "streets-navigation-vector"
})

Working with Map Services from ArcGIS Enterprise

MapImageLayer is used to display data from a Map Service in ArcGIS Enterprise. Map Services often contain multiple sub layers and complex cartography. Map Services render data as a server side image that is dynamically generated and displayed on the client.

Using raster and imagery data

ImageryLayer is used to display imagery or other raster based data stored in an Image Service in ArcGIS Enterprise. ImageryLayer is often used to display and analyze raw imagery data captured from drones or satellites or for displaying scientific data.

Data as collections of features

Layers are often used to manage and display large collections of features. Features are records of geographical locations or entities. Every feature contains spatial coordinates defined for a type of geometry (point, polyline, or polygon) and attribute fields that store other information. These collections of features can be thought of as:

  • Structured if every feature has the same geometry type and the same attributes keys
  • Unstructured if any features have different geometry types or different attributes keys

When working with a collection of features the general rule of thumb is:

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.