Create a heat chart | Overview | ArcGIS Maps SDK for JavaScript

Heat chart visualizes data in a matrix format, where individual values are represented as colors in cells. It is useful for identifying patterns, correlations, and outliers in large datasets.

In this tutorial, you will create and customize a heat chart using heat chart model and render it with the <arcgis-chart> component.

Prerequisites

Steps

Create a new pen

Go to CodePen to create a new pen for your application.

Add basic HTML

Define a basic HTML page.

In CodePen > HTML, add HTML to create a basic page.

Use dark colors for code blocks
<html>

<head>
  <meta charset="utf-8" />
  <meta name="viewport" content="initial-scale=1, maximum-scale=1, user-scalable=no" />
  <title>ArcGIS Maps SDK for JavaScript Tutorials: Create a heat chart with arcgis/charts-components</title>

  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

</head>


<body>

</body>


</html>

Add references

In the <head> tag, add references to the JavaScript SDK core library, calcite components and charts components.

Expand
Use dark colors for code blocks
  <style>
    html,
    body,
    arcgis-chart {
      height: 100%;
      margin: 0;
    }
  </style>

  <!-- Load Calcite components from CDN -->
  <script type="module" src="https://js.arcgis.com/calcite-components/3.3.3/calcite.esm.js"></script>

  <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
  <script src="https://js.arcgis.com/4.34/"></script>

  <!-- Load Charts components from CDN-->
  <script type="module" src="https://js.arcgis.com/4.34/charts-components/"></script>
Expand

Add chart component

In the <body> tag, add the <arcgis-chart> component.

Expand
Use dark colors for code blocks

<body>

  <arcgis-chart>

  </arcgis-chart>

</body>
Expand
Component reference (chart)

Add charts action bar component

Inside the <arcgis-chart> component, add the <arcgis-charts-action-bar> component and specify its slot.

Expand
Use dark colors for code blocks

<body>

  <arcgis-chart>

    <arcgis-charts-action-bar slot="action-bar"></arcgis-charts-action-bar>

  </arcgis-chart>

</body>
Expand
Component reference (charts action bar)

Add logic to create a chart

Within the <body> tag, add a <script> tag with type="module" to write JavaScript code to create a chart with charts model.

Expand
Use dark colors for code blocks
  <script type="module">

  </script>
Expand

Within the <script> tag, use @arcgis.import() to import the createModel function from @arcgis/charts-components and FeatureLayer from @arcgis/core/layers/FeatureLayer.js.

Expand
Use dark colors for code blocks
  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

  </script>
Expand

Load a feature layer from a portalItem that contains New York City hotel data that will be visualized in the heat chart.

Expand
Use dark colors for code blocks
  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "a8fbe2753beb4cd4aeef4d47e5e32a7c"
      }
    });

  </script>
Expand

Use document.querySelector() to select the <arcgis-chart> component.

Expand
Use dark colors for code blocks
  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "a8fbe2753beb4cd4aeef4d47e5e32a7c"
      }
    });

    const heatChartElement = document.querySelector("arcgis-chart");

  </script>
Expand

Use createModel() to create a new heat chart model with the feature layer. The chart type is set to heatChart.

Expand
Use dark colors for code blocks
  <script type="module">

    const { createModel } = await $arcgis.import("@arcgis/charts-components");
    const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");

    const featureLayer = new FeatureLayer({
      portalItem: {
        id: "a8fbe2753beb4cd4aeef4d47e5e32a7c"
      }
    });

    const heatChartElement = document.querySelector("arcgis-chart");

    const heatChartModel = await createModel({ layer: featureLayer, chartType: "heatChart" });

  </script>
Expand

Use charts model to customize the heat chart

In this section, we’ll explore how to use various properties and methods from the heat chart model together with the <arcgis-chart> component to customize a chart. Specifically, we’ll create a calendar heat chart — a type of heat chart that displays data in a calendar layout to reveal temporal patterns using date fields. Refer to the full list of available properties and methods in the heat chart model reference.

First, use the xAxisField and yAxisField properties to set the x-axis and y-axis fields. In this tutorial, we are using the last_review date field for both axes to create a calendar heat chart. You can use any date fields from your dataset.

Expand
Use dark colors for code blocks
    heatChartModel.xAxisField = "last_review";
    heatChartModel.yAxisField = "last_review";

Expand

Next, use the numericFields property and the aggregationType to set the numeric field and aggregation type. Here, we use the price field with the avg aggregation type to visualize the average hotel price for each day.

Expand
Use dark colors for code blocks
    heatChartModel.numericFields = ["price"];
    heatChartModel.aggregationType = "avg";

Expand

With a calendar heat chart, you can configure temporal binning independently for each axis. Use the xTemporalBinning and yTemporalBinning properties to define the temporal binning for the x-axis and y-axis, respectively. Since we want to visualize data for each day of the year, we set the x-axis binning to monthOfYear and the y-axis binning to dayOfMonth.

You can further customize the axis labels using the setAxisValueFormat method. Here, the x-axis is formatted to display full month names, while the y-axis shows day numbers.

Expand
Use dark colors for code blocks
    heatChartModel.xTemporalBinning = { unit: "monthOfYear" };
    heatChartModel.yTemporalBinning = { unit: "dayOfMonth" };
    heatChartModel.setAxisValueFormat(0, { type: "date", intlOptions: { month: "long" } });
    heatChartModel.setAxisValueFormat(1, { type: "date", intlOptions: { weekday: "long" } });

Expand

Use the gradientRules property to define color gradient rules for the heat chart. A gradient color from light blue to dark red is used here to represent low to high average hotel prices. minValue and maxValue are set to 100 and 250 to focus on a specific range of average prices. Outliers outside this range will be represented by the boundary colors set by outsideRangeLowerColor and outsideRangeUpperColor.

Expand
Use dark colors for code blocks
    heatChartModel.gradientRules = {
      colorList: [
        [200, 225, 255, 255],
        [220, 0, 0, 255],
      ],
      minValue: 100,
      maxValue: 250,
      outsideRangeLowerColor: [240, 248, 255, 255],
      outsideRangeUpperColor: [160, 30, 30, 255],
    };

Expand

Next, customize the heat chart title and subtitle by using the titleText and subtitleText properties. You can also use the setAxisTitleText method to set the title for each axis.

Expand
Use dark colors for code blocks
    heatChartModel.titleText = "Average Price of NYC Hotels";
    heatChartModel.subtitleText = "Grouped by Month of Year and Day of Month";
    heatChartModel.setAxisTitleText("Month", 0);
    heatChartModel.setAxisTitleText("Day", 1);

Expand

To visualize the price directly in the cell without hovering, you can set dataLabelsVisibility to true to enable data labels. This might make certain values hard to read due to color contrast, so you can use the autoInverseDataLabelTextColor property to invert data label colors based on the background color for better readability.

Expand
Use dark colors for code blocks
    heatChartModel.dataLabelsVisibility = true;
    heatChartElement.autoInverseDataLabelTextColor = true;

Expand

Set the model property of the heatChartElement to the heatChartModel to apply the configurations and render the chart.

Expand
Use dark colors for code blocks
    heatChartElement.model = heatChartModel;
Expand

Run the app

In CodePen, run your code to display the chart.

You should see a calendar heat chart that visualizes the average hotel price for each day of the year, with colors representing different price ranges. From the heat chart, you can easily identify patterns such as peak seasons and price fluctuations throughout the year.

What's next?

Learn how to use additional SDK features and ArcGIS services in these tutorials: