Styling and theming

In a chart, styling and theming choices help readers distinguish series, compare values, and recognize patterns. A consistent appearance also makes charts easier to interpret alongside the rest of your app.

• Styling: Target specific chart elements using charts model properties and methods.
• Theming: Apply a consistent visual style across your application with multiple components using CSS variables

Styling

Use charts model properties and methods to customize individual chart elements and emphasize important data without changing your application’s overall theme. The demo below brings these styling options together, and the sections that follow show how to customize each element.

Titles

Style chart titles individually to improve readability and visual hierarchy using titleSymbol for the chart title, subtitleSymbol for the subtitle, legendTitleSymbol for the legend title, and setAxisTitleSymbol for axis titles.

// Example of styling the chart title symbol using the titleSymbol property
barChartModel.titleSymbol = {
  type: "esriTS",
  color: [45, 62, 80, 255],
  font: {
    size: 18,
    weight: "bold",
  },
};

Series

Depending on the chart type, series represent data sets as bars, lines, slices, boxes, markers, or cells, and styling them helps readers distinguish between data sets and interpret the chart.

By default, colorMatch is enabled, so charts assign series colors in this order:

1. When renderer matching is supported for the chart type and configuration, colors are taken from the layer’s renderer. Set colorMatch to false to disable this behavior.
2. If renderer colors aren’t applied, colors defined in the charts model are used. Set custom series colors with the setSeriesColor method.

   // Example of setting custom series colors using the setSeriesColor method
   barChartModel.setSeriesColor([78, 121, 167, 255], 0);
   barChartModel.setSeriesColor([242, 142, 44, 255], 1);
   barChartModel.setSeriesColor([89, 161, 79, 255], 2);
3. If no colors are defined in the model, a default color ramp will be used to assign colors to the series.

Axes

Customize axis line color, width, and style with the axisLinesSymbol property, and adjust the appearance of axis labels with the axisLabelsSymbol property.

// Example of setting the axis lines symbol using the axisLinesSymbol property
// This will apply the specified style to all axis lines in the chart
barChartModel.axisLinesSymbol = {
  type: "esriSLS",
  style: "esriSLSSolid",
  color: [112, 125, 138, 255],
  width: 2,
};

// Example of setting the axis labels symbol using the axisLabelsSymbol property
// This will apply the specified style to all axis labels in the chart
barChartModel.axisLabelsSymbol = {
  type: "esriTS",
  color: [45, 62, 80, 255],
  font: {
    size: 12,
  },
};

Grid lines

Use the setGridLinesSymbol method to customize the appearance of all grid lines or target individual lines with specific parameters.

// Example of setting the grid lines symbol using the setGridLinesSymbol method
// This will apply the specified style to all grid lines in the chart without providing axisIndices as the second parameter
barChartModel.setGridLinesSymbol(
  {
    type: "esriSLS",
    style: "esriSLSSolid",
    color: [214, 220, 226, 255],
    width: 1,
  }
);

Legend

Multi-series charts show a legend by default to help readers identify each series. Legend markers reflect the chart type, such as filled squares for bars and lines for line charts. In bar charts, set legendRoundMarker to true to round square markers. You can also customize the legend title and item text with legendTitleSymbol and legendTextSymbol.

// Example of customizing the legend marker
barChartModel.legendRoundMarker = true;

// Example of customizing the legend title symbol
barChartModel.legendTitleSymbol = {
  type: "esriTS",
  color: [45, 62, 80, 255],
  font: {
    size: 14,
    weight: "bold",
  },
};
// Example of customizing the legend text symbol
barChartModel.legendTextSymbol = {
  type: "esriTS",
  color: [45, 62, 80, 255],
  font: {
    size: 12,
  },
};

Guides

Use setGuideStyle to customize a guide’s appearance, and setGuideTooltipReverseColor to reverse its tooltip text color for better contrast.

By default, guides appear behind the chart’s series, this can be changed by using the setGuideAbove method.

// Example of setting the guide style and reversing the tooltip text color for better contrast
barChartModel.setGuideStyle(
  {
    type: "esriSFS",
    color: [78, 121, 167, 45],
  },
  0,
);
barChartModel.setGuideTooltipReverseColor(true, 0);

Tooltips

By default, the data tooltip background matches the hovered series color, and the text color will automatically switch between black and white based on the background color.

Use setDataTooltipReverseColor to reverse the tooltip’s text, background, and border colors.

// Example of reversing the tooltip colors for all series
barChartModel.setDataTooltipReverseColor(true);

Selection

Use the chart component’s selectionTheme property to customize the appearance of selected and non-selected data items.

// Example of setting the selection theme for the chart component
chartElement.selectionTheme = {
  selectedElementsTheme: {
    elementOutlineColor: [45, 62, 80, 255],
    elementOutlineWidth: 3,
    transformation: {
      scale: 1.1,
    },
  },
  nonSelectedElementsTheme: {
    transformation: {
      scale: 0.8,
    },
  },
};

Theming

Theming allows you to apply a consistent visual style across your charts and other components within the application by leveraging CSS variables.

13 collapsed lines
1
<html>
2
  <head>
3
    <meta charset="utf-8" />
4
    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no" />
5
    <title>Bar chart with split by field</title>
6
    <style>
7
      html,
8
      body,
9
      arcgis-chart {
10
        height: 100%;
11
        margin: 0;
12
      }
13

14
      :root {
15
        /* Background: Dark gray */
16
        --calcite-color-foreground-1: #34404d;
17
        /* Text: Light gray */
18
        --calcite-color-text-1: #f8fafc;
19
        /* Axis lines: Light gray */
20
        --calcite-color-border-1: #aab7c4;
21
        /* Grid lines: Lighter gray */
22
        --calcite-color-text-3: #e2e2e2;
23
        /* Loading indicators: Light gray */
24
        --calcite-color-brand-hover: #f8fafc;
25
      }
49 collapsed lines
26

27
    </style>
28
    <!-- Load the ArcGIS Maps SDK for JavaScript from CDN -->
29
    <script type="module" src="https://js.arcgis.com/5.2/"></script>
30
  </head>
31

32
  <body>
33
    <arcgis-chart></arcgis-chart>
34
    <script type="module">
35
      const { createModel } = await $arcgis.import("@arcgis/charts-components/model/shared/setup-utils.js");
36
      const FeatureLayer = await $arcgis.import("@arcgis/core/layers/FeatureLayer.js");
37
      const featureLayer = new FeatureLayer({
38
        portalItem: {
39
          id: "a8fbe2753beb4cd4aeef4d47e5e32a7c",
40
        },
41
      });
42
      const chartElement = document.querySelector("arcgis-chart");
43
      const barChartModel = await createModel({ layer: featureLayer, chartType: "barChart" });
44
      barChartModel.xAxisField = "neighbourhood_group";
45
      barChartModel.splitByField = "room_type";
46
      barChartModel.addYAxisGuide("Guide 1", 0);
47
      barChartModel.setGuideStart(6000, 0);
48
      barChartModel.setGuideEnd(8000, 0);
49
      barChartModel.setGuideStyle(
50
        {
51
          type: "esriSFS",
52
          color: [255, 255, 255, 55],
53
        },
54
        0,
55
      );
56
      barChartModel.setGuideLabelText("Values between 6000 and 8000", 0);
57
      barChartModel.setGuideTooltipReverseColor(true, 0);
58
      barChartModel.setAxisTitleText("Neighbourhood Group", 0);
59
      barChartModel.titleText = "NYC Short-Term Rental Room Types by Neighbourhood Group";
60
      barChartModel.subtitleText = "Room counts by room type across the five boroughs";
61
      barChartModel.legendTitleText = "Room type";
62
      barChartModel.descriptionText =
63
        "Manhattan and Brooklyn have the highest room counts, with a different room type leading in each borough.";
64
      barChartModel.dataLabelsVisibility = true;
65
      barChartModel.legendPosition = "right";
66
      barChartModel.setAxisValueFormat(0, {
67
        type: "category",
68
        characterLimit: 20,
69
      });
70
      chartElement.model = barChartModel;
71
      chartElement.actionMode = "none";
72
    </script>
73
  </body>
74
</html>