ArcGIS Layers Skill | Agent Skills

ArcGIS Layers

Use this skill when adding, configuring, or querying data layers in ArcGIS maps.

Import Patterns

Direct ESM Imports

import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";
import GraphicsLayer from "@arcgis/core/layers/GraphicsLayer.js";
import GeoJSONLayer from "@arcgis/core/layers/GeoJSONLayer.js";

Dynamic Imports (CDN)

const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
const [GraphicsLayer, Graphic] = await $arcgis.import([
  "@arcgis/core/layers/GraphicsLayer.js",
  "@arcgis/core/Graphic.js"
]);

Layer Types Overview

| Layer Type | Use Case | Geometry | |------------|----------|----------| | FeatureLayer | Most common - feature services, editable data | Points, lines, polygons | | GraphicsLayer | Client-side temporary graphics | Any | | GeoJSONLayer | GeoJSON files/URLs | Points, lines, polygons | | CSVLayer | CSV files with coordinates | Points | | TileLayer | Cached map tiles | Raster | | VectorTileLayer | Vector tiles (Mapbox style) | Vector | | ImageryTileLayer | Raster imagery | Raster | | SceneLayer | 3D buildings, meshes | 3D objects | | IntegratedMeshLayer | Photogrammetry meshes | 3D mesh | | PointCloudLayer | LiDAR point clouds | Points | | ParquetLayer | Apache Parquet files | Points, lines, polygons | | StreamLayer | Real-time WebSocket data | Points, lines, polygons |

FeatureLayer

From URL

import FeatureLayer from "@arcgis/core/layers/FeatureLayer.js";

const featureLayer = new FeatureLayer({
  url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/Landscape_Trees/FeatureServer/0",
  outFields: ["*"],
  popupTemplate: {
    title: "{Tree_ID}",
    content: "Height: {Crown_Height} ft"
  }
});

map.add(featureLayer);

From Portal Item

const featureLayer = new FeatureLayer({
  portalItem: {
    id: "51c851fef66143959986b473b345b7ca"
  },
  outFields: ["*"]
});

Client-Side (In-Memory)

const featureLayer = new FeatureLayer({
  source: graphics, // Array of Graphic objects
  fields: [
    { name: "ObjectID", type: "oid" },
    { name: "name", type: "string" },
    { name: "value", type: "double" }
  ],
  objectIdField: "ObjectID",
  geometryType: "point",
  spatialReference: { wkid: 4326 },
  renderer: {
    type: "simple",
    symbol: { type: "simple-marker", color: "blue" }
  }
});

Configuration Options

const featureLayer = new FeatureLayer({
  url: "...",
  outFields: ["*"],           // Fields to include (* = all)
  definitionExpression: "population > 10000", // SQL filter
  minScale: 500000,           // Hide when zoomed out beyond this
  maxScale: 0,                // Hide when zoomed in beyond this
  visible: true,              // Initial visibility
  opacity: 0.8,               // Transparency (0-1)
  title: "Cities",            // Display name
  blendMode: "normal",        // Blend mode for compositing
  orderBy: [{ field: "population" }], // Feature draw order
  featureReduction: null,     // Clustering / binning config
  labelingInfo: [...],        // Labels
  renderer: {...},            // Symbology
  popupTemplate: {...},       // Popup configuration
  elevationInfo: {            // 3D elevation mode
    mode: "relative-to-ground"
  }
});

GraphicsLayer

import GraphicsLayer from "@arcgis/core/layers/GraphicsLayer.js";
import Graphic from "@arcgis/core/Graphic.js";

const graphicsLayer = new GraphicsLayer();
map.add(graphicsLayer);

// Add a point
const pointGraphic = new Graphic({
  geometry: {
    type: "point",
    longitude: -118.24,
    latitude: 34.05
  },
  symbol: {
    type: "simple-marker",
    color: "red",
    size: 12
  },
  attributes: { name: "Los Angeles" },
  popupTemplate: { title: "{name}" }
});

graphicsLayer.add(pointGraphic);

// Add multiple graphics
graphicsLayer.addMany([graphic1, graphic2, graphic3]);

// Remove graphics
graphicsLayer.remove(pointGraphic);
graphicsLayer.removeAll();

GeoJSONLayer

import GeoJSONLayer from "@arcgis/core/layers/GeoJSONLayer.js";

const geojsonLayer = new GeoJSONLayer({
  url: "https://earthquake.usgs.gov/earthquakes/feed/v1.0/summary/all_month.geojson",
  copyright: "USGS Earthquakes",
  popupTemplate: {
    title: "Earthquake Info",
    content: "Magnitude {mag} hit {place} on {time}",
    fieldInfos: [{
      fieldName: "time",
      format: { dateFormat: "short-date-short-time" }
    }]
  },
  renderer: {
    type: "simple",
    symbol: { type: "simple-marker", color: "orange" },
    visualVariables: [{
      type: "size",
      field: "mag",
      stops: [
        { value: 2.5, size: "4px" },
        { value: 8, size: "40px" }
      ]
    }]
  },
  orderBy: [{ field: "mag" }] // Draw smaller on top
});

map.add(geojsonLayer);

CSVLayer

import CSVLayer from "@arcgis/core/layers/CSVLayer.js";

const csvLayer = new CSVLayer({
  url: "https://example.com/data.csv",
  latitudeField: "latitude",  // Column name for lat
  longitudeField: "longitude", // Column name for lon
  delimiter: ",",
  popupTemplate: {
    title: "{name}",
    content: "{description}"
  }
});

TileLayer (Cached Tiles)

import TileLayer from "@arcgis/core/layers/TileLayer.js";

const tileLayer = new TileLayer({
  url: "https://services.arcgisonline.com/ArcGIS/rest/services/World_Street_Map/MapServer"
});

map.add(tileLayer);

VectorTileLayer

import VectorTileLayer from "@arcgis/core/layers/VectorTileLayer.js";

// From portal item
const vtl = new VectorTileLayer({
  portalItem: { id: "VECTOR_TILE_ITEM_ID" }
});

// From URL
const vtl2 = new VectorTileLayer({
  url: "https://basemaps.arcgis.com/v1/arcgis/rest/services/World_Basemap/VectorTileServer"
});

ImageryTileLayer

import ImageryTileLayer from "@arcgis/core/layers/ImageryTileLayer.js";

const imageryLayer = new ImageryTileLayer({
  url: "https://tiledimageservices.arcgis.com/..."
});

// From Cloud Optimized GeoTIFF (COG)
const cogLayer = new ImageryTileLayer({
  url: "https://example.com/image.tif"
});

3D Layers

SceneLayer (3D Buildings)

import SceneLayer from "@arcgis/core/layers/SceneLayer.js";

const sceneLayer = new SceneLayer({
  portalItem: { id: "2e0761b9a4274b8db52c4bf34356911e" },
  popupEnabled: false
});

// Add to SceneView map
map.add(sceneLayer);

// Custom 3D symbology
sceneLayer.renderer = {
  type: "simple",
  symbol: {
    type: "mesh-3d",
    symbolLayers: [{
      type: "fill",
      material: { color: [244, 247, 134] }
    }]
  }
};

IntegratedMeshLayer

import IntegratedMeshLayer from "@arcgis/core/layers/IntegratedMeshLayer.js";

const meshLayer = new IntegratedMeshLayer({
  url: "https://tiles.arcgis.com/tiles/.../IntegratedMeshServer"
});

PointCloudLayer

import PointCloudLayer from "@arcgis/core/layers/PointCloudLayer.js";

const pcLayer = new PointCloudLayer({
  url: "https://tiles.arcgis.com/tiles/.../SceneServer"
});

Specialized Layers

For WMS, WFS, KML, MapImageLayer, and CatalogLayer, see arcgis-advanced-layers.

StreamLayer (Real-time)

import StreamLayer from "@arcgis/core/layers/StreamLayer.js";

const streamLayer = new StreamLayer({
  url: "wss://example.com/stream/service",
  purgeOptions: {
    displayCount: 10000
  }
});

ParquetLayer (File-based)

import ParquetLayer from "@arcgis/core/layers/ParquetLayer.js";

const parquetLayer = new ParquetLayer({
  urls: [
    "https://example.com/data.parquet"
  ],
  title: "Parquet Data",
  renderer: {
    type: "simple",
    symbol: { type: "simple-marker", color: "blue" }
  },
  popupTemplate: {
    title: "{name}",
    content: [{
      type: "fields",
      fieldInfos: [
        { fieldName: "field1", label: "Field 1" }
      ]
    }]
  }
});

// Query feature count
const count = await parquetLayer.queryFeatureCount();

GeoRSSLayer

import GeoRSSLayer from "@arcgis/core/layers/GeoRSSLayer.js";

const georssLayer = new GeoRSSLayer({
  url: "https://example.com/feed.xml"
});

map.add(georssLayer);

// Zoom to layer extent
await view.whenLayerView(georssLayer);
view.goTo(georssLayer.fullExtent);

WebTileLayer

import WebTileLayer from "@arcgis/core/layers/WebTileLayer.js";

// OpenStreetMap tiles
const osmLayer = new WebTileLayer({
  urlTemplate: "https://{subDomain}.tile.openstreetmap.org/{z}/{x}/{y}.png",
  subDomains: ["a", "b", "c"],
  copyright: "OpenStreetMap contributors"
});

// Custom tile service
const customTileLayer = new WebTileLayer({
  urlTemplate: "https://tiles.example.com/{level}/{col}/{row}.png"
});

map.add(osmLayer);

MapNotesLayer

import MapNotesLayer from "@arcgis/core/layers/MapNotesLayer.js";

// Layer for sketches and annotations
const notesLayer = new MapNotesLayer();
map.add(notesLayer);

// Access sublayers
const pointLayer = notesLayer.pointLayer;
const polylineLayer = notesLayer.polylineLayer;
const polygonLayer = notesLayer.polygonLayer;
const textLayer = notesLayer.textLayer;

// Add a text annotation
const textGraphic = new Graphic({
  geometry: point,
  symbol: {
    type: "text",
    text: "Note here",
    color: [255, 255, 255],
    haloColor: [0, 0, 0],
    haloSize: 2,
    font: { family: "Arial", size: 14 }
  }
});
textLayer.add(textGraphic);

Layer Management

Adding Layers

// Add single layer
map.add(layer);

// Add at specific index (0 = bottom)
map.add(layer, 0);

// Add multiple layers
map.addMany([layer1, layer2, layer3]);

// Add to Map Component
const viewElement = document.querySelector("arcgis-map");
viewElement.map.add(layer);

Removing Layers

map.remove(layer);
map.removeMany([layer1, layer2]);
map.removeAll();

Layer Ordering

// Reorder layer
map.reorder(layer, newIndex);

// Get layer position
const index = map.layers.indexOf(layer);

// Find layer by id
const layer = map.findLayerById("myLayerId");

// Find layer by title
const layer = map.layers.find(l => l.title === "Cities");

Visibility and Opacity

layer.visible = false;
layer.opacity = 0.5; // 0-1

// Watch visibility changes
import * as reactiveUtils from "@arcgis/core/core/reactiveUtils.js";

reactiveUtils.watch(
  () => layer.visible,
  (newValue) => console.log("Visibility changed:", newValue)
);

Querying Features

Basic Query

// Create query from layer settings
const query = featureLayer.createQuery();
query.where = "population > 100000";
query.outFields = ["name", "population"];
query.returnGeometry = true;

const result = await featureLayer.queryFeatures(query);
console.log(result.features); // Array of Graphic objects

Query with Pagination

const query = featureLayer.createQuery();
query.start = 0;       // Start index
query.num = 20;        // Number of features
query.orderByFields = ["population DESC"];

const result = await featureLayer.queryFeatures(query);

Spatial Query

const query = featureLayer.createQuery();
query.geometry = view.extent; // Or any geometry
query.spatialRelationship = "intersects"; // contains, crosses, etc.
query.returnGeometry = true;

const result = await featureLayer.queryFeatures(query);

Count Query

const count = await featureLayer.queryFeatureCount();
console.log("Total features:", count);

Extent Query

const result = await featureLayer.queryExtent();
console.log("Feature count:", result.count);
await view.goTo(result.extent);

Statistics Query

const query = featureLayer.createQuery();
query.outStatistics = [{
  statisticType: "sum",
  onStatisticField: "population",
  outStatisticFieldName: "totalPop"
}, {
  statisticType: "avg",
  onStatisticField: "population",
  outStatisticFieldName: "avgPop"
}];

const result = await featureLayer.queryFeatures(query);
console.log(result.features[0].attributes.totalPop);

Query from LayerView (Client-side)

const layerView = await view.whenLayerView(featureLayer);

// Query only currently visible features
const query = layerView.createQuery();
query.geometry = view.extent;

const result = await layerView.queryFeatures(query);

Query Methods Reference

| Method | Returns | Use When | |--------|---------|----------| | queryFeatures(query) | FeatureSet (graphics) | You need the actual feature data | | queryObjectIds(query) | number[] (OIDs) | You only need IDs for highlighting | | queryFeatureCount(query) | number | You need a count without fetching data | | queryExtent(query) | { count, extent } | You want to zoom to matching features | | queryRelatedFeatures(params) | Related feature sets | You need related table records | | queryAttachments(params) | AttachmentInfo[] | You need file attachments |

Server vs Client-side Queries

| Aspect | featureLayer.queryFeatures() | layerView.queryFeatures() | |--------|-------------------------------|----------------------------| | Runs on | Server | Client (browser) | | Data scope | All features in service | Only features in view/cache | | Network cost | HTTP request per call | No network (already loaded) | | Use when | Need full dataset, pagination, stats | Need fast filtering of visible features |

Layer Loading

// Wait for layer to load
await featureLayer.load();
console.log("Fields:", featureLayer.fields);
console.log("Extent:", featureLayer.fullExtent);

// Wait for layer view
const layerView = await view.whenLayerView(featureLayer);

// Check if updating
reactiveUtils.watch(
  () => layerView.updating,
  (updating) => {
    if (!updating) {
      console.log("Layer view finished updating");
    }
  }
);

Definition Expressions (Filters)

// SQL WHERE clause filter
featureLayer.definitionExpression = "state = 'California'";

// Clear filter
featureLayer.definitionExpression = null;

// Dynamic filter
function filterByYear(year) {
  featureLayer.definitionExpression = `year = ${year}`;
}

TypeScript Usage

Layer configurations with type properties support autocasting. For TypeScript safety, use as const:

// Use 'as const' for type safety
const featureLayer = new FeatureLayer({
  source: graphics,
  fields: [
    { name: "ObjectID", type: "oid" },
    { name: "name", type: "string" }
  ],
  geometryType: "point",
  renderer: {
    type: "simple",
    symbol: { type: "simple-marker", color: "blue" }
  } as const
});

For complex layer configurations, use type annotations:

const renderer: __esri.SimpleRendererProperties = {
  type: "simple",
  symbol: { type: "simple-marker", color: "blue" }
};

layer.renderer = renderer;

Tip: See arcgis-core-maps for detailed guidance on autocasting vs explicit classes.

Reference Samples

intro-layers - Introduction to working with layers
layers-featurelayer - FeatureLayer configuration and usage
layers-geojson - Loading GeoJSON data as a layer
featurelayer-query - Querying features from a FeatureLayer
get-started-graphics - Working with Graphics and GraphicsLayer

Related Skills

See arcgis-core-maps for map and view setup.
See arcgis-visualization for renderers, symbols, and visual variables.
See arcgis-popup-templates for popup configuration.
See arcgis-editing for feature editing with applyEdits.
See arcgis-advanced-layers for WMS, WFS, KML, MapImageLayer, CatalogLayer.
See arcgis-3d-layers for 3D-specific layer configuration.

Common Pitfalls

CORS errors with GeoJSON: GeoJSON URLs must be CORS-enabled or use a proxy.

Missing outFields: Queries return no attribute values unless outFields is specified.

// Anti-pattern: querying without outFields
const results = await featureLayer.queryFeatures({
  where: "population > 100000",
  returnGeometry: true
});
console.log(results.features[0].attributes.name); // undefined

// Correct: specify outFields to include desired attributes
const results = await featureLayer.queryFeatures({
  where: "population > 100000",
  returnGeometry: true,
  outFields: ["name", "population", "state"]
});
console.log(results.features[0].attributes.name); // "Los Angeles"

Impact: Feature attributes come back as undefined or null. The query succeeds but the response contains no usable attribute data, leading to silent data bugs.

Not waiting for layer load: Layer metadata (fields, extent, renderer) is unavailable until the layer finishes loading.

// Anti-pattern: accessing properties before load
const layer = new FeatureLayer({ url: "https://services.arcgis.com/.../FeatureServer/0" });
console.log(layer.fields); // null - layer has not loaded yet
console.log(layer.fullExtent); // null

// Correct: await layer.load() first
const layer = new FeatureLayer({ url: "https://services.arcgis.com/.../FeatureServer/0" });
await layer.load();
console.log(layer.fields); // Array of Field objects
console.log(layer.fullExtent); // Extent object

Impact: fields is null or an empty array, fullExtent is null, and any code that depends on layer metadata throws errors or silently fails.

Wrong layer for MapView vs SceneView: Some layers only work in 3D (SceneLayer, IntegratedMeshLayer, PointCloudLayer).

Spatial reference mismatch: Adding layers with a different spatial reference than the view without projection support.

// Anti-pattern: adding a layer in a different SR without handling projection
const view = new MapView({
  spatialReference: { wkid: 4326 } // WGS84
});
const layer = new FeatureLayer({
  url: "https://services.arcgis.com/.../FeatureServer/0" // Data in Web Mercator (3857)
});
view.map.add(layer); // Features may render in wrong location

// Correct: match spatial references or load the projection engine
import * as projection from "@arcgis/core/geometry/projection.js";
await projection.load();

const view = new MapView({
  spatialReference: { wkid: 4326 }
});
const layer = new FeatureLayer({
  url: "https://services.arcgis.com/.../FeatureServer/0"
});
view.map.add(layer); // Projection engine handles the transformation

Impact: Features appear in the wrong location, are offset by thousands of kilometers, or do not display at all when spatial references are incompatible.

Agent Skills: ArcGIS Layers

Install this agent skill to your local

Skill Files