Visual variables | ArcGIS Maps SDK for JavaScript

Weather stations styled with a simple render and visual variables to show air temperature

What are visual variables?

Visual variables are objects that allow you to override one or more properties of a renderer’s symbols based on a numeric data value returned from a field or an expression. This is an alternative to visualizing numeric data with a class breaks style. Rather than separate values into discrete ranges of data, visual variables linearly interpolate between data stops to create a smooth, continuous (unclassed) visualization.

There are four visual variables that can be overridden with data values.

Color
Size
Opacity
Rotation

How visual variables work

All visual variables are added to a renderer’s visualVariables property. A renderer can contain more than one visual variable, but adding more than one at a time may cause confusion.

Multivariate visualizations

Learn how to style layers with a simple renderer using 2D and 3D symbols.

Color

A color variable overrides the color of a symbol based on a numeric data value returned from a field or expression along a continuous color ramp. Numeric data should be normalized before visualizing it with color, especially for polygon layers.

Color visual variables require the following:

A reference to a data value either from a field name, or an Arcade expression.
At least two color stops that match data values to colors. The colors of symbols with data values between the designated stops are linearly interpolated.

The following example renders the current temperature reported by weather stations along a continuous color ramp.

ArcGIS JS API


44 collapsed lines
1
<!doctype html>
2
<html>
3
  <head>
4
    <meta charset="utf-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
6
    <title>Esri Developer Guide: Visual variables (color)</title>
7
    <style>
8
      html,
9
      body,
10
      #viewDiv {
11
        height: 100%;
12
        margin: 0;
13
      }
14
    </style>
15

16
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
17
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
18
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
19

20
    <script type="module">
21
      const [Map, MapView, FeatureLayer, Legend, Expand] = await $arcgis.import([
22
        "@arcgis/core/Map.js",
23
        "@arcgis/core/views/MapView.js",
24
        "@arcgis/core/layers/FeatureLayer.js",
25
        "@arcgis/core/widgets/Legend.js",
26
        "@arcgis/core/widgets/Expand.js",
27
      ]);
28

29
      const referenceScale = 9244650 * 4;
30

31

32
      const renderer = {
33
        type: "simple",
34
        symbol: {
35
          type: "simple-marker",
36
          style: "circle",
37
          color: [250, 250, 250],
38
          outline: {
39
            color: [255, 255, 255, 0.5],
40
            width: 0.5,
41
          },
42
          size: "8px",
43
        },
44

45
        visualVariables: [
46
          {
47
            type: "color",
48
            field: "TEMP",
49
            stops: [
50
              { value: 20, color: "#2b83ba" },
51
              { value: 35, color: "#abdda4" },
52
              { value: 50, color: "#ffffbf" },
53
              { value: 65, color: "#fdae61" },
54
              { value: 80, color: "#d7191c" },
55
            ],
56
          },
57
        ],
48 collapsed lines
58

59
      };
60

61

62
      // Set the renderer on the feature layer
63
      const layer = new FeatureLayer({
64
        portalItem: {
65
          id: "cb1886ff0a9d4156ba4d2fadd7e8a139",
66
        },
67
        title: "Current weather conditions",
68
        renderer: renderer,
69
      });
70

71
      const map = new Map({
72
        basemap: {
73
          portalItem: {
74
            id: "ba223f982a3c4a0ea8c9953346e2a201",
75
          },
76
        },
77
        layers: [layer],
78
      });
79

80
      const view = new MapView({
81
        container: "viewDiv",
82
        map: map,
83
        scale: referenceScale,
84
        center: [-95, 38.5],
85
        constraints: {
86
          snapToZoom: false,
87
        },
88
      });
89

90
      view.ui.add(
91
        new Expand({
92
          content: new Legend({
93
            view: view,
94
          }),
95
          view: view,
96
          expanded: false,
97
        }),
98
        "top-right",
99
      );
100
    </script>
101
  </head>
102
  <body>
103
    <div id="viewDiv"></div>
104
  </body>
105
</html>

Size

A size variable overrides the size of a symbol based on a numeric data value returned from a field or expression. This does not apply to renderers with fill symbols. To visualize a polygon layer by size, you should use a marker symbol, which will be rendered at the centroid of the polygon.

The size visual variable can be defined in two different ways:

With size stops, or
Matching a maxDataValue with a maxSize, and a minDataValue with a minSize.

Size visual variables require the following:

A reference to a data value either from a field name, or an Arcade expression.
At least two size stops that match data values to sizes. The sizes of symbols with data values between the designated stops are linearly interpolated.

The following example renders the current wind speed reported by weather stations along a continuous size ramp.

ArcGIS JS API


44 collapsed lines
1
<!doctype html>
2
<html>
3
  <head>
4
    <meta charset="utf-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
6
    <title>Size visual variable</title>
7
    <style>
8
      html,
9
      body,
10
      #viewDiv {
11
        height: 100%;
12
        margin: 0;
13
      }
14
    </style>
15

16
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
17
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
18
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
19

20
    <script type="module">
21
      const [Map, MapView, FeatureLayer, Legend, Expand] = await $arcgis.import([
22
        "@arcgis/core/Map.js",
23
        "@arcgis/core/views/MapView.js",
24
        "@arcgis/core/layers/FeatureLayer.js",
25
        "@arcgis/core/widgets/Legend.js",
26
        "@arcgis/core/widgets/Expand.js",
27
      ]);
28

29
      const referenceScale = 9244650 * 2;
30

31

32
      const renderer = {
33
        type: "simple",
34
        symbol: {
35
          type: "simple-marker",
36
          style: "circle",
37
          color: [50, 50, 50, 0.4],
38
          outline: {
39
            color: [255, 255, 255, 0.3],
40
            width: 0.2,
41
          },
42
          size: "8px",
43
        },
44

45
        visualVariables: [
46
          {
47
            type: "size",
48
            field: "WIND_SPEED",
49
            minDataValue: 5,
50
            maxDataValue: 60,
51
            minSize: 4,
52
            maxSize: 22,
53
          },
54
        ],
48 collapsed lines
55

56
      };
57

58

59
      // Set the renderer on the feature layer
60
      const layer = new FeatureLayer({
61
        portalItem: {
62
          id: "cb1886ff0a9d4156ba4d2fadd7e8a139",
63
        },
64
        title: "Current weather conditions",
65
        renderer: renderer,
66
      });
67

68
      const map = new Map({
69
        basemap: {
70
          portalItem: {
71
            id: "ba223f982a3c4a0ea8c9953346e2a201",
72
          },
73
        },
74
        layers: [layer],
75
      });
76

77
      const view = new MapView({
78
        container: "viewDiv",
79
        map: map,
80
        scale: referenceScale,
81
        center: [-95, 38.5],
82
        constraints: {
83
          snapToZoom: false,
84
        },
85
      });
86

87
      view.ui.add(
88
        new Expand({
89
          content: new Legend({
90
            view: view,
91
          }),
92
          view: view,
93
          expanded: false,
94
        }),
95
        "top-right",
96
      );
97
    </script>
98
  </head>
99
  <body>
100
    <div id="viewDiv"></div>
101
  </body>
102
</html>

Rotation

A rotation variable sets the rotation of a symbol based on a numeric data value returned from a field or expression. This is typically done to rotate symbols that indicate directionality, such as:

wind direction
traffic flow
aspect

Rotation visual variables are different from other visual variables in that they only require a data value without the need for stops.

A reference to a data value either from a field name, or an Arcade expression.
An optional rotation type indicating a geometry or arithmetic rotation.

The following example visualizes weather stations with arrow markers and rotates them based on wind direction.

ArcGIS JS API


46 collapsed lines
1
<!doctype html>
2
<html>
3
  <head>
4
    <meta charset="utf-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
6
    <title>Rotation visual variable</title>
7
    <style>
8
      html,
9
      body,
10
      #viewDiv {
11
        height: 100%;
12
        margin: 0;
13
      }
14
    </style>
15

16
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/light/main.css" />
17
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
18
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
19

20
    <script type="module">
21
      const [Map, MapView, FeatureLayer, Legend, Expand] = await $arcgis.import([
22
        "@arcgis/core/Map.js",
23
        "@arcgis/core/views/MapView.js",
24
        "@arcgis/core/layers/FeatureLayer.js",
25
        "@arcgis/core/widgets/Legend.js",
26
        "@arcgis/core/widgets/Expand.js",
27
      ]);
28

29
      const referenceScale = 9244650 * 2;
30

31

32
      const renderer = {
33
        type: "simple",
34
        symbol: {
35
          type: "simple-marker",
36
          // Arrow marker defined as SVG path
37
          path: "M14.5,29 23.5,0 14.5,9 5.5,0z",
38
          color: [50, 50, 50],
39
          outline: {
40
            color: [255, 255, 255, 0.5],
41
            width: 0.5,
42
          },
43
          angle: 180,
44
          size: "20px",
45
        },
46

47
        visualVariables: [
48
          {
49
            type: "rotation",
50
            field: "WIND_DIRECT",
51
            rotationType: "geographic",
52
          },
53
        ],
48 collapsed lines
54

55
      };
56

57

58
      // Set the renderer on the feature layer
59
      const layer = new FeatureLayer({
60
        portalItem: {
61
          id: "cb1886ff0a9d4156ba4d2fadd7e8a139",
62
        },
63
        title: "Current weather conditions",
64
        renderer: renderer,
65
      });
66

67
      const map = new Map({
68
        basemap: {
69
          portalItem: {
70
            id: "ba223f982a3c4a0ea8c9953346e2a201",
71
          },
72
        },
73
        layers: [layer],
74
      });
75

76
      const view = new MapView({
77
        container: "viewDiv",
78
        map: map,
79
        scale: referenceScale,
80
        center: [-95, 38.5],
81
        constraints: {
82
          snapToZoom: false,
83
        },
84
      });
85

86
      view.ui.add(
87
        new Expand({
88
          content: new Legend({
89
            view: view,
90
          }),
91
          view: view,
92
          expanded: false,
93
        }),
94
        "top-right",
95
      );
96
    </script>
97
  </head>
98
  <body>
99
    <div id="viewDiv"></div>
100
  </body>
101
</html>

Opacity

An opacity variable overrides the opacity of a symbol based on a numeric data value returned from a field or expression. This variable is typically used to subdue features or make some more prominent than others.

Opacity visual variables require the following:

A reference to a data value either from a field name or an Arcade expression.
At least two opacity stops that match data values to opacity values between 0 and 1. The opacity of symbols with data values between the designated stops are linearly interpolated.

The following example visualizes the predominant crop for each U.S. county. The renderer has an opacity variable to emphasize counties with a lot of cropland and subdue counties that have very little cropland by comparison.

ArcGIS JS API


69 collapsed lines
1
<!doctype html>
2
<html>
3
  <head>
4
    <meta charset="utf-8" />
5
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
6
    <title>Esri Developer Guide: Visual variables (opacity)</title>
7
    <style>
8
      html,
9
      body,
10
      #viewDiv {
11
        height: 100%;
12
        margin: 0;
13
      }
14
    </style>
15

16
    <link rel="stylesheet" href="https://js.arcgis.com/5.0/esri/themes/dark/main.css" />
17
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
18
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
19

20
    <script type="module">
21
      const [Map, MapView, FeatureLayer, Legend, Expand] = await $arcgis.import([
22
        "@arcgis/core/Map.js",
23
        "@arcgis/core/views/MapView.js",
24
        "@arcgis/core/layers/FeatureLayer.js",
25
        "@arcgis/core/widgets/Legend.js",
26
        "@arcgis/core/widgets/Expand.js",
27
      ]);
28

29
      const referenceScale = 9244650 * 2;
30

31
      function createSymbol(color) {
32
        return {
33
          type: "simple-fill",
34
          outline: {
35
            color: "rgba(50,50,50,0.1)",
36
            width: 0.5,
37
          },
38
          color,
39
          style: "solid",
40
        };
41
      }
42

43

44
      const renderer = {
45
        type: "unique-value",
46
        field: "DOM_CROP_ACRES",
47
        uniqueValueInfos: [
48
          {
49
            value: "Corn",
50
            symbol: createSymbol("#e6d800"),
51
          },
52
          {
53
            value: "Wheat",
54
            symbol: createSymbol("#9b19f5"),
55
          },
56
          {
57
            value: "Soybeans",
58
            symbol: createSymbol("#0bb4ff"),
59
          },
60
          {
61
            value: "Cotton",
62
            symbol: createSymbol("#50e991"),
63
          },
64
          {
65
            value: "Vegetables",
66
            symbol: createSymbol("#e60049"),
67
          },
68
        ],
69

70
        visualVariables: [
71
          {
72
            type: "opacity",
73
            field: "TotalFarmedAcres",
74
            normalizationField: "AREA_ACRES",
75
            legendOptions: {
76
              showLegend: false,
77
            },
78
            stops: [
79
              { value: 0.0, opacity: 0.2 },
80
              { value: 0.1, opacity: 0.5 },
81
              { value: 0.5, opacity: 0.8 },
82
              { value: 0.9, opacity: 1.0 },
83
            ],
84
          },
85
        ],
43 collapsed lines
86

87
      };
88

89

90
      // Set the renderer on the feature layer
91
      const layer = new FeatureLayer({
92
        url: "https://services.arcgis.com/V6ZHFr6zdgNZuVG0/arcgis/rest/services/US_county_crops_2007_clean/FeatureServer/0",
93
        title: "U.S. counties",
94
        renderer: renderer,
95
      });
96

97
      const map = new Map({
98
        basemap: "dark-gray-vector",
99
        layers: [layer],
100
      });
101

102
      const view = new MapView({
103
        container: "viewDiv",
104
        map: map,
105
        scale: referenceScale,
106
        center: [-95, 38.5],
107
        constraints: {
108
          snapToZoom: false,
109
        },
110
      });
111

112
      view.ui.add(
113
        new Expand({
114
          content: new Legend({
115
            view: view,
116
          }),
117
          view: view,
118
          expanded: false,
119
        }),
120
        "top-right",
121
      );
122
    </script>
123
  </head>
124

125
  <body>
126
    <div id="viewDiv"></div>
127
  </body>
128
</html>

API support

	3D	Lines	Polygons	Mesh
Unique types
Class breaks
Visual variables				¹
Time
Multivariate
Predominance
Dot density
Charts
Relationship
Smart Mapping	²	³	³	³

Full SupportPartial SupportNo Support

Color only
Size variable creators only supported for points
Size variable creators not supported in 3D

Data-driven stylesClass breaks Data-driven stylesTime

What are visual variables?

How visual variables work

Multivariate visualizations

Color

Size

Rotation

Opacity

Related samples and resources

Data-driven continuous color

Size visual variable themes

Data-driven extrusion

Visualize data with rotation

Data-driven continuous size

Data-driven opacity

Generate data-driven continuous size visualization

Thematic visualization with realistic 3D symbols

API support