Time | ArcGIS Maps SDK for JavaScript

Incidents styled with a simple render, visual variables, and clusters to show number of days to close

What are time styles?

Time styles include all visualizations that involve date/time data. You can use these styles to visualize when and where an event occurs. Common examples involve the following:

Timeline
Before and after
Age
Track visualization
Time series animation

Examples

Timeline

A timeline visualization displays date/time data along a continuous color ramp. It provides an immediate view at when phenomena occurred or when a value was recorded relative to all other data points.

The following example visualizes hurricane locations in the Atlantic Ocean recorded in the year 2000. This uses a color visual variable to show which hurricanes occurred early in the season versus late in the season.


43 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

7
    <title>Esri Developer Guide: Hurricane location and timeline</title>
8

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

13
    <style>
14
      html,
15
      body,
16
      #viewDiv {
17
        height: 100%;
18
        margin: 0;
19
      }
20
    </style>
21

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

31

32
      const renderer = {
33
        type: "simple",
34
        label: "Observed hurricane location",
35
        symbol: {
36
          type: "simple-marker",
37
          size: 6,
38
          outline: {
39
            width: 0.5,
40
            color: [255, 255, 255, 0.5],
41
          },
42
        },
43

44
        visualVariables: [
45
          {
46
            type: "color",
47
            field: "Date_Time",
48
            legendOptions: {
49
              title: "Date of observation",
50
            },
51
            stops: [
52
              { value: new Date(2000, 7, 3).getTime(), color: "#00ffff" },
53
              { value: new Date(2000, 9, 22).getTime(), color: "#2f3f56" },
54
            ],
55
          },
56
        ],
43 collapsed lines
57

58
      };
59

60

61
      const layer = new FeatureLayer({
62
        url: "https://sampleserver6.arcgisonline.com/arcgis/rest/services/Hurricanes/MapServer/0",
63
        renderer: renderer,
64
      });
65

66
      const map = new WebMap({
67
        portalItem: {
68
          id: "9cf503b654144873a8e33f996f91ba1d",
69
        },
70
        layers: [layer],
71
      });
72

73
      const view = new MapView({
74
        container: "viewDiv",
75
        map: map,
76
        scale: 36978595,
77
        center: [-44.0632, 33.1567],
78
        constraints: {
79
          snapToZoom: false,
80
        },
81
      });
82

83
      view.ui.add(
84
        new Expand({
85
          content: new Legend({
86
            view: view,
87
          }),
88
          view: view,
89
          expanded: true,
90
        }),
91
        "top-right",
92
      );
93
    </script>
94
  </head>
95

96
  <body>
97
    <div id="viewDiv"></div>
98
  </body>
99
</html>

Before and after

You can use a color visual variable with a diverging color ramp to visualize which events occurred before and after a specific date.

The following example visualizes clusters of hurricane locations summarized by whether they occurred before or after July 1st.


41 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

7
    <title>Esri Developer Guide: Hurricane locations before or after 1977</title>
8

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

13
    <style>
14
      html,
15
      body,
16
      #viewDiv {
17
        height: 100%;
18
        margin: 0;
19
      }
20
    </style>
21

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

31

32
      const colors = ["#54bebe", "#dedad2", "#c80064"];
33
      const renderer = {
34
        type: "simple",
35
        label: "Observed hurricane location",
36
        symbol: {
37
          type: "simple-marker",
38
          size: 4,
39
          outline: null,
40
        },
41

42
        visualVariables: [
43
          {
44
            type: "color",
45
            field: "ISO_time",
46
            legendOptions: {
47
              title: "Before and after July 1",
48
            },
49
            stops: [
50
              { value: new Date(2013, 0, 1).getTime(), color: colors[0], label: "January 1" },
51
              { value: new Date(2013, 6, 1).getTime(), color: colors[1], label: "July 1" },
52
              { value: new Date(2013, 11, 31).getTime(), color: colors[2], label: "December 31" },
53
            ],
54
          },
55
        ],
51 collapsed lines
56

57
      };
58

59

60
      // ISO_time
61

62
      const layer = new FeatureLayer({
63
        title: "2013 Hurricane season",
64
        portalItem: {
65
          id: "f14573e9c5ce4b41aecb199d5723209b",
66
        },
67
        renderer: renderer,
68
        definitionExpression: "Season = 2013",
69
      });
70

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

80
      const view = new MapView({
81
        container: "viewDiv",
82
        map: map,
83
        scale: 136195673,
84
        constraints: {
85
          snapToZoom: false,
86
          rotationEnabled: false,
87
        },
88
      });
89

90
      view.ui.add(
91
        new Expand({
92
          content: new Legend({
93
            view: view,
94
          }),
95
          view: view,
96
          expanded: true,
97
        }),
98
        "top-right",
99
      );
100
    </script>
101
  </head>
102

103
  <body>
104
    <div id="viewDiv"></div>
105
  </body>
106
</html>

Age

An age visualization shows the age of a feature (or the elapsed time up to a meaningful date or the current date) based on a date field. Age visualizations may be applied in the following scenarios:

How long has an asset been in commission?
How old is the incident report?
How long has it been since the last inspection?
Is an incident past due for resolution?

Age is typically defined using the DateDiff function in an Arcade expression and mapped with a color or size variable. It specifies a length of time with desired units.

valueExpression = "DateDiff( Now(), $feature.date_created, 'hours' )"

The following example visualizes clustered street condition complaints in New York City based on how much time passed before the incident was closed relative to its due date.


56 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

7
    <title>Esri Developer Guide: Street condition complaints</title>
8

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

13
    <style>
14
      html,
15
      body,
16
      #viewDiv {
17
        height: 100%;
18
        margin: 0;
19
      }
20
    </style>
21

22
    <script type="module">
23
      const [
24
        WebMap,
25
        MapView,
26
        FeatureLayer,
27
        Legend,
28
        Expand,
29
        clusterLabelCreator,
30
        clusterPopupCreator,
31
        promiseUtils,
32
      ] = await $arcgis.import([
33
        "@arcgis/core/WebMap.js",
34
        "@arcgis/core/views/MapView.js",
35
        "@arcgis/core/layers/FeatureLayer.js",
36
        "@arcgis/core/widgets/Legend.js",
37
        "@arcgis/core/widgets/Expand.js",
38
        "@arcgis/core/smartMapping/labels/clusters.js",
39
        "@arcgis/core/smartMapping/popup/clusters.js",
40
        "@arcgis/core/core/promiseUtils.js",
41
      ]);
42

43

44
      const colors = ["#2799ff", "#423a3a", "#ff3333"];
45
      const renderer = {
46
        type: "simple",
47
        label: "Observed hurricane location",
48
        symbol: {
49
          type: "simple-marker",
50
          size: 6,
51
          outline: {
52
            width: 0.5,
53
            color: [255, 255, 255, 0.5],
54
          },
55
        },
56

57
        visualVariables: [
58
          {
59
            type: "color",
60
            valueExpression: "DateDiff($feature['closed_time'], $feature['due_time'], 'days')",
61
            valueExpressionTitle: "Days it took to close incident",
62
            stops: [
63
              { value: -21, color: colors[0], label: "21 weeks early" },
64
              { value: 0, color: colors[1], label: "On time" },
65
              { value: 21, color: colors[2], label: "21 weeks late" },
66
            ],
67
          },
68
        ],
97 collapsed lines
69

70
      };
71

72

73
      const layer = new FeatureLayer({
74
        portalItem: {
75
          id: "f624a9f4afa947fe98acd0ed38fbe436",
76
        },
77
        title: "Street condition complaints",
78
        renderer: renderer,
79
        definitionExpression: "Complaint_Type = 'Street Condition'",
80
      });
81

82
      const map = new WebMap({
83
        portalItem: {
84
          id: "75a3ce8990674a5ebd5b9ab66bdab893",
85
        },
86
        layers: [layer],
87
      });
88

89
      const view = new MapView({
90
        container: "viewDiv",
91
        map: map,
92
        scale: 144447,
93
        center: [-73.863, 40.7],
94
        constraints: {
95
          snapToZoom: false,
96
        },
97
      });
98

99
      view.ui.add(
100
        new Expand({
101
          content: new Legend({
102
            view: view,
103
          }),
104
          view: view,
105
          expanded: true,
106
        }),
107
        "top-right",
108
      );
109

110
      view
111
        .when()
112
        .then(generateClusterConfig)
113
        .then(function (featureReduction) {
114
          layer.featureReduction = featureReduction;
115
        });
116

117
      function generateClusterConfig() {
118
        // generates default popupTemplate
119
        const popupPromise = clusterPopupCreator
120
          .getTemplates({
121
            layer: layer,
122
          })
123
          .then(function (popupTemplateResponse) {
124
            return popupTemplateResponse.primaryTemplate.value;
125
          });
126

127
        // generates default labelingInfo
128
        const labelPromise = clusterLabelCreator
129
          .getLabelSchemes({
130
            layer: layer,
131
            view: view,
132
          })
133
          .then(function (labelSchemes) {
134
            return labelSchemes.primaryScheme;
135
          });
136

137
        return promiseUtils
138
          .eachAlways([popupPromise, labelPromise])
139
          .then(function (result) {
140
            const popupTemplate = result[0].value;
141

142
            const primaryLabelScheme = result[1].value;
143
            const labelingInfo = primaryLabelScheme.labelingInfo;
144
            // Ensures the clusters are large enough to fit labels
145
            const clusterMinSize = primaryLabelScheme.clusterMinSize;
146

147
            return {
148
              type: "cluster",
149
              popupTemplate: popupTemplate,
150
              labelingInfo: labelingInfo,
151
              clusterMinSize: clusterMinSize,
152
              clusterRadius: 50,
153
            };
154
          })
155
          .catch(function (error) {
156
            console.error(error);
157
          });
158
      }
159
    </script>
160
  </head>
161

162
  <body>
163
    <div id="viewDiv"></div>
164
  </body>
165
</html>

Track visualization

Track data is represented as a series of observations (typically points). In addition to a timestamp, each observation must belong to a track identified by a unique ID. This ID is used to group observations into a track. To render track data, the layer must be configured with a valid timeInfo.

The timeInfo property of the layer defines the following:

startField: The field representing the time the observation occurred.
trackIdField: The field containing the unique ID of the track the observation belongs to.

layer.timeInfo = {
  startField: "ISO_time",
  trackIdField: "Serial_Num"
};

The layer in this example represents historic hurricane locations as points. To render each hurricane tracks as paths, you must also set the trackInfo property of the layer. The trackInfo property defines the following properties:

previousObservations: Defines how to render the previous observations of the track. In this example, previous locations are rendered as simple markers with color and size visual variables to indicate the strength of the hurricane.
latestObservations: Defines how to render the latest observations of the track relative to the time slider. In this example, the latest hurricane observations are rendered as animated markers resembling a hurricane’s shape with a size visual variable to indicate the strength of the hurricane.
trackLine: Defines how to render the track line. In this example, the track line is rendered as a simple line.

The renderers listed above also include opacity visual variables to indicate the age of the observation relative to the time slider. The older the observation, the more transparent it appears until it fades out completely.

This requires a TimeSlider component for control over the time.

The basic trackInfo configuration is stubbed out below. Open the code editor above to see the full configuration.

layer.trackInfo = {
  previousObservations: {
    renderer: {
      // renderer configuration defined here
    },
    labelingInfo: [
      // labelingInfo configuration defined here
    ]
  },
  latestObservations: {
    renderer: {
      // renderer configuration defined here
    },
    labelingInfo: [
      // labelingInfo configuration defined here
    ]
  },
  trackLine: {
    renderer: {
      // renderer configuration defined here
    },
    labelingInfo: [
      // labelingInfo configuration defined here
    ]
  }
};

Time series animation

Time series animations are visualizations showing how data values change over time in features fixed at unchanging locations. These typically involve a time slider so users have the ability to explore moments of time or time windows.

For features that have a static position (such as sensors, buildings, countries, etc.), but have attributes that vary over time (e.g. POPULATION_2000, POPULATION_2005, POPULATION_2010, etc.), Arcade expressions can access time slider values to dynamically reference the field name corresponding to the current time on the slider. This allows you to visualize how data changes over time without needing to filter features or download duplicate geometries.

In this example, the temperature anomaly layer has field names representing temperature anomalies for each year from 1880 to 2020 in this format: F1900, F1901, F1902, …, F2020. The Arcade expression uses the time slider value to dynamically reference the field name for the year represented by the slider value.

The underlying rendering engine re-executes the expression with every slider value change.

First, configure the time slider to match the start and end dates of the data with the appropriate time interval.


26 collapsed lines
1
<!doctype html>
2
<html lang="en">
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: Time series animation</title>
7

8
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
9
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
10
  </head>
11

12
  <body>
13
    <calcite-shell>
14
      <arcgis-map item-id="74a5a5d2e6784ef19578cbce8c808886">
15
        <arcgis-legend slot="top-left"></arcgis-legend>
16
      </arcgis-map>
17
      <calcite-shell-panel id="slider-panel" slot="panel-bottom">
18
        <arcgis-time-slider
19
          layout="auto"
20
          mode="instant"
21
          reference-element="arcgis-map"></arcgis-time-slider>
22
      </calcite-shell-panel>
23
    </calcite-shell>
24

25
    <script type="module">
26

27
      const yearSlider = document.querySelector("arcgis-time-slider");
28
      yearSlider.fullTimeExtent = {
29
        start: new Date(1880, 0, 1),
30
        end: new Date(2018, 0, 1),
31
      };
32
      yearSlider.timeExtent = {
33
        start: new Date(1880, 0, 1),
34
        end: new Date(1880, 0, 1),
35
      };
36
      yearSlider.stops = {
37
        interval: {
38
          value: 1,
39
          unit: "years",
40
        },
41
      };
54 collapsed lines
42

43

44
      const viewElement = document.querySelector("arcgis-map");
45
      viewElement.timeExtent = yearSlider.timeExtent;
46

47
      viewElement.addEventListener("arcgisViewReadyChange", async () => {
48
        const view = viewElement.view;
49
        const layer = view.map.layers.getItemAt(0);
50
        const renderer = layer.renderer.clone();
51
        // Updates the underlying data value driving the expression
52
        // based on the given year provided by the slider
53

54
        const sizeVisualVariable = renderer.visualVariables.find(
55
          (visualVariable) => visualVariable.type === "size",
56
        );
57

58
        // Returns the value of the "F{year}" field based on the slider's value.
59
        // This expression will re-execute every time the slider's value changes
60
        const valueExpression = `
61
          Expects($feature, "F*");
62
          if(HasValue($view, ["timeProperties", "currentEnd"])){
63
            var y = Year($view.timeProperties.currentEnd);
64
            var value = $feature["F" + y];
65
            return value;
66
          }
67
          return null;
68
        `;
69

70

71
        // Update legend text to be more user friendly
72
        const valueExpressionTitle = "Are temperatures significantly warmer or colder than normal?";
73

74
        // Replace the field with the valueExpression so the user can dynamically
75
        // explore the data as it changed from year to year
76
        renderer.field = null;
77
        renderer.valueExpression = valueExpression;
78
        renderer.valueExpressionTitle = valueExpressionTitle;
79

80
        // Since this is an above-and-below size renderer, we need to update
81
        // the size visual variable to reflect the new valueExpression
82
        sizeVisualVariable.field = null;
83
        sizeVisualVariable.valueExpression = valueExpression;
84
        sizeVisualVariable.valueExpressionTitle = valueExpressionTitle;
85
        // Update legend text to be more user friendly
86
        sizeVisualVariable.stops[0].label = "Colder";
87
        sizeVisualVariable.stops[2].label = "Normal";
88
        sizeVisualVariable.stops[4].label = "Warmer";
89

90
        renderer.visualVariables = [sizeVisualVariable];
91
        layer.renderer = renderer;
92
      });
93
    </script>
94
  </body>
95
</html>

Next, update the layer’s renderer to use an Arcade expression that references the time slider value to dynamically access the field name for the year represented by the slider value.


53 collapsed lines
1
<!doctype html>
2
<html lang="en">
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: Time series animation</title>
7

8
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
9
    <script type="module" src="https://js.arcgis.com/5.0/"></script>
10
  </head>
11

12
  <body>
13
    <calcite-shell>
14
      <arcgis-map item-id="74a5a5d2e6784ef19578cbce8c808886">
15
        <arcgis-legend slot="top-left"></arcgis-legend>
16
      </arcgis-map>
17
      <calcite-shell-panel id="slider-panel" slot="panel-bottom">
18
        <arcgis-time-slider
19
          layout="auto"
20
          mode="instant"
21
          reference-element="arcgis-map"></arcgis-time-slider>
22
      </calcite-shell-panel>
23
    </calcite-shell>
24

25
    <script type="module">
26

27
      const yearSlider = document.querySelector("arcgis-time-slider");
28
      yearSlider.fullTimeExtent = {
29
        start: new Date(1880, 0, 1),
30
        end: new Date(2018, 0, 1),
31
      };
32
      yearSlider.timeExtent = {
33
        start: new Date(1880, 0, 1),
34
        end: new Date(1880, 0, 1),
35
      };
36
      yearSlider.stops = {
37
        interval: {
38
          value: 1,
39
          unit: "years",
40
        },
41
      };
42

43

44
      const viewElement = document.querySelector("arcgis-map");
45
      viewElement.timeExtent = yearSlider.timeExtent;
46

47
      viewElement.addEventListener("arcgisViewReadyChange", async () => {
48
        const view = viewElement.view;
49
        const layer = view.map.layers.getItemAt(0);
50
        const renderer = layer.renderer.clone();
51
        // Updates the underlying data value driving the expression
52
        // based on the given year provided by the slider
53

54
        const sizeVisualVariable = renderer.visualVariables.find(
55
          (visualVariable) => visualVariable.type === "size",
56
        );
57

58
        // Returns the value of the "F{year}" field based on the slider's value.
59
        // This expression will re-execute every time the slider's value changes
60
        const valueExpression = `
61
          Expects($feature, "F*");
62
          if(HasValue($view, ["timeProperties", "currentEnd"])){
63
            var y = Year($view.timeProperties.currentEnd);
64
            var value = $feature["F" + y];
65
            return value;
66
          }
67
          return null;
68
        `;
27 collapsed lines
69

70

71
        // Update legend text to be more user friendly
72
        const valueExpressionTitle = "Are temperatures significantly warmer or colder than normal?";
73

74
        // Replace the field with the valueExpression so the user can dynamically
75
        // explore the data as it changed from year to year
76
        renderer.field = null;
77
        renderer.valueExpression = valueExpression;
78
        renderer.valueExpressionTitle = valueExpressionTitle;
79

80
        // Since this is an above-and-below size renderer, we need to update
81
        // the size visual variable to reflect the new valueExpression
82
        sizeVisualVariable.field = null;
83
        sizeVisualVariable.valueExpression = valueExpression;
84
        sizeVisualVariable.valueExpressionTitle = valueExpressionTitle;
85
        // Update legend text to be more user friendly
86
        sizeVisualVariable.stops[0].label = "Colder";
87
        sizeVisualVariable.stops[2].label = "Normal";
88
        sizeVisualVariable.stops[4].label = "Warmer";
89

90
        renderer.visualVariables = [sizeVisualVariable];
91
        layer.renderer = renderer;
92
      });
93
    </script>
94
  </body>
95
</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 stylesVisual variables Data-driven stylesMultivariate

What are time styles?

Examples

Timeline

Before and after

Age

Track visualization

Time series animation

Related samples and resources

Filter features with TimeSlider component

TimeSlider component

TimeSlider with timeOffset and actions

Animate color visual variable

Update a renderer's attribute

Six ways to visualize change over time in web maps

API support