arcgis-feature-effects

ArcGIS Feature Effects

Use this skill for applying visual effects, feature filters, display filters, focus areas, and blend modes to layers.

Import Patterns

Direct ESM Imports

import FeatureEffect from "@arcgis/core/layers/support/FeatureEffect.js";
import FeatureFilter from "@arcgis/core/layers/support/FeatureFilter.js";
import FocusArea from "@arcgis/core/effects/FocusArea.js";
import FocusAreas from "@arcgis/core/effects/FocusAreas.js";
import FocusAreaOutline from "@arcgis/core/effects/FocusAreaOutline.js";

CDN Dynamic Imports

const [FeatureEffect, FeatureFilter, FocusArea] = await $arcgis.import([
  "@arcgis/core/layers/support/FeatureEffect.js",
  "@arcgis/core/layers/support/FeatureFilter.js",
  "@arcgis/core/effects/FocusArea.js",
]);

Note: Examples below use autocasting. For CDN usage, replace import X from "path" with const X = await $arcgis.import("path").

Feature Effect Basics

Feature effects divide features into two sets (included/excluded) based on a filter, then apply CSS-like effects to each set.

Basic Feature Effect

layer.featureEffect = {
  filter: {
    where: "population > 100000",
  },
  includedEffect: "bloom(1.5, 0.5px, 0.2)",
  excludedEffect: "grayscale(100%) opacity(30%)",
};

Feature Effect on LayerView

const layerView = await view.whenLayerView(layer);

layerView.featureEffect = {
  filter: {
    where: "status = 'Active'",
  },
  excludedEffect: "grayscale(100%) opacity(50%)",
};

Scale-Dependent Effects

layerView.featureEffect = {
  filter: {
    where: "party_switch = 'R' OR party_switch = 'D'",
  },
  includedEffect: [
    { scale: 36978595, value: "drop-shadow(3px, 3px, 4px)" },
    { scale: 18489297, value: "drop-shadow(2px, 2px, 3px)" },
    { scale: 4622324, value: "drop-shadow(1px, 1px, 2px)" },
  ],
};

Effect Types Reference

Effect	Syntax	Description
opacity	opacity(50%)	Transparency (0-100%)
grayscale	grayscale(100%)	Remove color (0-100%)
blur	blur(5px)	Gaussian blur
drop-shadow	drop-shadow(x, y, blur, color)	Shadow effect
bloom	bloom(strength, radius, threshold)	Glow effect
brightness	brightness(150%)	Adjust brightness
contrast	contrast(120%)	Adjust contrast
invert	invert(100%)	Invert colors
sepia	sepia(100%)	Sepia tone
saturate	saturate(200%)	Color saturation
hue-rotate	hue-rotate(180deg)	Rotate hue

Individual Effect Examples

Opacity

layer.featureEffect = {
  filter: { where: "type = 'primary'" },
  excludedEffect: "opacity(25%)",
};

Grayscale

layer.featureEffect = {
  filter: { where: "category = 'important'" },
  excludedEffect: "grayscale(100%)",
};

Blur

layer.featureEffect = {
  filter: { where: "highlighted = 1" },
  excludedEffect: "blur(5px)",
};

Drop Shadow

layer.featureEffect = {
  filter: { where: "selected = 1" },
  includedEffect: "drop-shadow(3px, 3px, 4px, #000000)",
};

Bloom (Glow)

layer.featureEffect = {
  filter: { where: "active = 1" },
  includedEffect: "bloom(1.5, 0.5px, 0.2)",
};

Brightness and Contrast

layer.featureEffect = {
  filter: { where: "status = 'highlight'" },
  includedEffect: "brightness(150%) contrast(120%)",
  excludedEffect: "brightness(50%)",
};

Combining Multiple Effects

layer.featureEffect = {
  filter: { where: "status = 'active'" },
  includedEffect: "drop-shadow(2px, 2px, 3px) brightness(120%)",
  excludedEffect: "grayscale(100%) opacity(30%) blur(2px)",
};

Filter Types

Attribute Filter

layer.featureEffect = {
  filter: {
    where: "population > 50000 AND state = 'CA'",
  },
  excludedEffect: "grayscale(100%) opacity(30%)",
};

Geometry-Based Filter

const layerView = await view.whenLayerView(layer);

layerView.featureEffect = {
  filter: {
    geometry: polygon,
    spatialRelationship: "intersects",
  },
  excludedEffect: "grayscale(100%) opacity(30%)",
};

Distance-Based Filter

layerView.featureEffect = {
  filter: {
    geometry: point,
    spatialRelationship: "intersects",
    distance: 1000,
    units: "meters",
  },
  excludedEffect: "opacity(20%)",
};

ObjectID Filter

layerView.featureEffect = {
  filter: {
    objectIds: [1, 5, 10, 42],
  },
  includedEffect: "drop-shadow(3px, 3px, 4px)",
  excludedEffect: "grayscale(100%) opacity(40%)",
};

Time-Based Filter

layer.featureEffect = {
  filter: {
    timeExtent: {
      start: new Date("2020-01-01"),
      end: new Date("2020-12-31"),
    },
  },
  excludedEffect: "opacity(20%)",
};

Spatial Relationships

Relationship	Description
intersects	Features that intersect the geometry
contains	Features that contain the geometry
within	Features within the geometry
crosses	Features that cross the geometry
overlaps	Features that overlap the geometry
touches	Features that touch the geometry
disjoint	Features not intersecting the geometry
envelope-intersects	Envelope intersection (faster)

Focus Areas (3D SceneView)

Focus areas highlight specific polygon regions in a 3D SceneView, dimming everything outside. Useful for drawing attention to areas of interest in 3D scenes.

Creating a Focus Area

import FocusArea from "@arcgis/core/effects/FocusArea.js";
import Collection from "@arcgis/core/core/Collection.js";

const focusArea = new FocusArea({
  title: "Area of Interest",
  id: "focus-1",
  enabled: true,
  outline: { color: [255, 128, 128, 0.55] },
  geometries: new Collection([polygon]),
});

Adding to a SceneView

// Add focus area to the view
view.focusAreas.areas.add(focusArea);

// Set visual style: "bright" or "dark"
view.focusAreas.style = "bright";

Toggling Focus Areas

// Disable without removing
focusArea.enabled = false;

// Re-enable with different style
focusArea.enabled = true;
view.focusAreas.style = "dark";

// Remove entirely
view.focusAreas.areas.remove(focusArea);

FocusArea Properties

Property	Type	Description
title	string	Title of the focus area
id	string	Unique identifier (auto-generated if omitted)
enabled	boolean	Whether displayed (default: true)
geometries	Collection<Polygon>	Polygon geometries defining the focus
outline	FocusAreaOutline	Outline style: { color }

Layer Effects (Non-Feature)

Apply CSS-like effects to an entire layer (not per-feature).

// Apply effect to the whole layer
layer.effect = "bloom(1.5, 0.5px, 0.2)";

// Multiple effects
layer.effect = "drop-shadow(3px, 3px, 4px) brightness(120%)";

// Remove effect
layer.effect = null;

Blend Modes

Blend modes control how a layer blends with layers beneath it.

layer.blendMode = "multiply"; // Default is "normal"

Blend Mode Categories

Category	Modes
Darkening	multiply, darken, color-burn
Lightening	screen, lighten, color-dodge
Contrast	overlay, soft-light, hard-light
Component	hue, saturation, luminosity, color
Composite	destination-in, destination-out, destination-over, source-in
Inversion	difference, exclusion, minus
Other	normal, average, vivid-light, reflect

Common Blend Mode Patterns

// Darken: show dark features on light basemap
layer.blendMode = "multiply";

// Lighten: show light features on dark basemap
layer.blendMode = "screen";

// Masking: clip layers using another layer shape
maskLayer.blendMode = "destination-in";

Display Filters

Display filters completely hide features (better performance than effects since features are not rendered).

Simple Display Filter

layer.displayFilterInfo = {
  where: "population > 10000",
};

Scale-Dependent Display Filter

const layer = new FeatureLayer({
  url: "https://services.arcgis.com/.../FeatureServer/0",
  displayFilterInfo: {
    mode: "scale",
    filters: [
      {
        title: "Major rivers",
        minScale: 0,
        maxScale: 36_978_595,
        where: "streamOrder >= 8",
      },
      {
        title: "Large rivers",
        minScale: 36_978_595,
        maxScale: 18_489_297,
        where: "streamOrder >= 7",
      },
      {
        title: "All rivers",
        minScale: 4_622_324,
        maxScale: 0,
      },
    ],
  },
});

Checking Active Display Filter

const layerView = await view.whenLayerView(layer);
const activeFilter = layerView.effectiveDisplayFilter?.title;

Combining Display Filter with Feature Effect

// Display filter hides deleted features entirely (performance)
layer.displayFilterInfo = {
  where: "status != 'deleted'",
};

// Feature effect styles remaining features
layer.featureEffect = {
  filter: { where: "status = 'active'" },
  excludedEffect: "opacity(50%)",
};

Interactive Feature Effects

Effect on Click

view.on("click", async (event) => {
  const response = await view.hitTest(event);
  const graphic = response.results[0]?.graphic;

  if (graphic) {
    const oid = graphic.attributes.OBJECTID;
    layerView.featureEffect = {
      filter: {
        objectIds: [oid],
      },
      includedEffect: "drop-shadow(3px, 3px, 4px)",
      excludedEffect: "grayscale(100%) opacity(40%)",
    };
  }
});

Effect with Slider

slider.on("thumb-drag", (event) => {
  const value = event.value;
  layer.featureEffect = {
    filter: { where: `value > ${value}` },
    excludedEffect: `opacity(${100 - value}%)`,
  };
});

Clear Feature Effect

layer.featureEffect = null;
// or
layerView.featureEffect = null;

Effect with Histogram

import histogram from "@arcgis/core/smartMapping/statistics/histogram.js";

const histogramResult = await histogram({
  layer: layer,
  field: "population",
  numBins: 30,
});

const slider = new HistogramRangeSlider({
  bins: histogramResult.bins,
  min: histogramResult.minValue,
  max: histogramResult.maxValue,
  values: [histogramResult.minValue, histogramResult.maxValue],
});

slider.on("thumb-drag", () => {
  const [min, max] = slider.values;
  layerView.featureEffect = {
    filter: {
      where: `population >= ${min} AND population <= ${max}`,
    },
    excludedEffect: "grayscale(100%) opacity(30%)",
  };
});

Reference Samples

• featureeffect-geometry - Geometry-based feature effects with spatial relationships
• featureeffect-drop-shadow - Scale-dependent drop shadow effects
• featureeffect-layers-histogram - Feature effects with histogram widget
• featureeffect-multiple-effects - Combining multiple visual effects
• effect-blur-shadow - Blur and shadow effects on layers
• intro-effect-layer - Introduction to layer effects
• display-filter - Scale-dependent display filtering
• focus-area - Focus areas in 3D SceneView
• highlight-features-by-geometry - Highlight features using geometry
• blendmode-darkening - Blend mode darkening effects
• blendmode-grouplayer - Blend modes on group layers
• blendmode-multiple-layers - Blend modes across multiple layers

Common Pitfalls

1. Layer vs LayerView: Feature effects on layer affect all views; on layerView only that specific view.

   // Affects all views
   layer.featureEffect = { ... };
   
   // Affects only this view
   const layerView = await view.whenLayerView(layer);
   layerView.featureEffect = { ... };
   

2. Performance: Complex effects (blur, bloom) on many features impact rendering performance. Use display filters to reduce the feature count first.

3. Effect order: When combining effects, they are applied in the order listed in the string.

4. Display filter vs feature effect: Use displayFilterInfo to hide features entirely (better performance). Use featureEffect to style included/excluded sets differently.

5. Time extent filter: Time-based filters require the layer to have time info configured. Without it, the filter is silently ignored.

6. Spatial filter on LayerView only: Geometry-based filters (geometry, distance) only work on layerView.featureEffect, not layer.featureEffect.

7. Bloom parameters: bloom(strength, radius, threshold) - threshold (0-1) controls which brightness level starts glowing. Higher values = less glow.

8. Effect string syntax: Effects are space-separated, not comma-separated. Incorrect syntax fails silently.

   // Anti-pattern: comma-separated effects
   excludedEffect: "grayscale(100%), opacity(30%)";
   
   // Correct: space-separated effects
   excludedEffect: "grayscale(100%) opacity(30%)";
   

9. Focus areas require Polygon geometry: Only Polygon geometry is supported for FocusArea.geometries. Points and polylines are not supported.

10. Scale-dependent effects: When using the array format for scale-dependent effects, provide at least two stops for smooth interpolation between scales.

Related Skills

• arcgis-visualization - Renderers and symbols
• arcgis-smart-mapping - Auto-generated renderers with histogram
• arcgis-interaction - User interaction and hit testing
• arcgis-layers - Layer types and configuration
• arcgis-core-maps - Map and view setup