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

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

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

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

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