> For the complete documentation index, see [llms.txt](https://docs.avonnicomponents.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.avonnicomponents.com/dynamic-components/components/chart.md).

# Chart

The Avonni Chart component turns Salesforce data into interactive visualizations — bar charts, column charts, line charts, donuts, gauges, pyramids, radar charts, and more — directly on a Lightning Page. No code required.

## Overview

When you add a Chart to the canvas, you choose the chart type from a preset list: **Bar Chart**, **Column Chart**, **Combo Chart**, **Donut Chart**, **Flat Gauge Chart**, **Gauge Chart**, **Line Chart**, **Metrics Radar Chart**, **Pyramid Chart**, **Stacked Bar Chart**, **Stacked Column Chart**, **Stacked Pyramid Chart**, **Heatmap Chart**, or **Treemap Chart**. The chart type is selected at the time you add the component; all 14 presets are variants of the same underlying Chart component and share the same configuration panel.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FKD1aQtFlnuUOvzAIlFyT%2Fchart-types.png?alt=media" alt="Six of the chart types, all built from the same Opportunity query"><figcaption><p>Six of the chart types, all built from the same Opportunity query</p></figcaption></figure>

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FNazTw6994ymxcRmUpmG0%2Fchart-heatmap-treemap.png?alt=media" alt="A heatmap and a treemap over the same Opportunity query"><figcaption><p>Heatmap and Treemap, the two types added in the 1.54 release</p></figcaption></figure>

{% hint style="info" %}
**See it in a real project**

[Bookings stacked by region](https://docs.avonnicomponents.com/projects/use-cases/reporting/bookings-stacked-by-region): Twelve months of bookings, every column stacked by region.
{% endhint %}

## Configuration

To configure the Chart, select it on the canvas. The **Edit Chart** panel opens on the right with two tabs: **Properties** and **Style**. The sections below mirror the Properties tab.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FG4ZrmnhHVSDnNhJGVrMX%2Fchart-builder-properties.png?alt=media" alt="The Chart Properties tab, with a Query data source and its data mappings" width="320"><figcaption><p>The Chart Properties tab, with a Query data source and its data mappings</p></figcaption></figure>

### Data Source

Before you can display anything, you must tell the Chart where to get its data. Two sources are supported:

| Source       | Description                                                                                                             |
| ------------ | ----------------------------------------------------------------------------------------------------------------------- |
| **Query**    | Fetch records directly from a Salesforce object. Choose the object, add filters to limit results, and set a sort order. |
| **Variable** | Use a page variable that already holds the records you want to chart.                                                   |

### Data Mapping

The **Data Mappings** section turns your records into chart series. There are only ever two or three slots: one that groups your records and one that measures them, plus an occasional third. **The panel renames them for the chart type you picked**, so the labels in front of you depend on **Type**.

| Type                                     | Grouping slot             | Measured slot         | Also                           |
| ---------------------------------------- | ------------------------- | --------------------- | ------------------------------ |
| Bar, Stacked Bar, Column, Stacked Column | **Bars**                  | **Bar Length**        | **Bar Segments**, stacked only |
| Pyramid, Stacked Pyramid                 | **Bars**                  | **Left & Right Axis** | **Bar Segments**, stacked only |
| Line                                     | **X-Axis**                | **Y-Axis**            | **Lines**                      |
| Combo                                    | **X-Axis**                | **Y-Axis**            |                                |
| Metrics Radar                            | **Polygons**              | **Axes**              |                                |
| Donut                                    | **Sliced By**             | **Value**             |                                |
| Gauge, Flat Gauge                        | none                      | **Value**             |                                |
| Heatmap                                  | **X-Axis** and **Y-Axis** | **Value**             |                                |
| Treemap                                  | **Segments**              | **Segment Size**      |                                |

So a bar chart maps a Stage field to **Bars** and an Amount field to **Bar Length**, and the same donut maps Stage to **Sliced By** and Amount to **Value**. Most slots take one field: **Bars** accepts several on a bar or column chart, **Segments** accepts two on a treemap, and the rest accept one.

Each grouping entry has three settings:

| Setting                      | What it does                                                                                                                       |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Field**                    | The Salesforce field whose values become the categories.                                                                           |
| **Group**                    | For a date field, the period to group by: Year, Quarter, Month, Week, Day, Year-Quarter, Year-Month, Year-Week, or Year-Month-Day. |
| **Display Full Month Label** | Spells months out in full. Appears only when **Group** is Month or Year-Month.                                                     |

Each measured entry has five:

| Setting          | What it does                                                                                                          |
| ---------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Field**        | The Salesforce numeric field to aggregate. The four settings below appear once it is set.                             |
| **Measures**     | The aggregation: Average, Count, Maximum, Median, Minimum, Sum, Unique, First, or Last.                               |
| **Format Style** | How the result is displayed: Number, Number Rounded, Percent, Percent Rounded, Currency, Currency Rounded, or Custom. |
| **Format**       | A format pattern of your own. Appears only when **Format Style** is Custom.                                           |
| **Multiplier**   | An optional multiplier applied to the aggregated value. Default: 1.                                                   |

A **Combo** chart is built entirely in its **Y-Axis** slot: add one entry per series and set each entry's **Display As** to **Line**, **Bar** or **Dot**. That choice, not the chart type, decides how each series is drawn.

### Content

The Content group controls the visual identity of the chart, and applies to every type.

| Property               | What it does                                                                                                                                                                 |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Type**               | The chart type chosen when you added the component. You can change it here at any time, to any of the 14 presets.                                                            |
| **Title**              | A heading displayed at the top of the chart.                                                                                                                                 |
| **Subtitle**           | Secondary text displayed below the title.                                                                                                                                    |
| **Title Font Size**    | 10, 11, 12, 14, 16, 18, 20, 24, 32, 48, or 64. Default: 14.                                                                                                                  |
| **Subtitle Font Size** | The same sizes as the title. Default: 12.                                                                                                                                    |
| **Title Alignment**    | Left (default), Center, or Right. Applies to the title, the subtitle and the description together.                                                                           |
| **X Title**            | Label for the horizontal axis.                                                                                                                                               |
| **Y Title**            | Label for the vertical axis.                                                                                                                                                 |
| **Palette**            | The colors used for the series: Aurora (default), Nightfall, Wildflowers, Sunrise, Bluegrass, Ocean, Heat, Dusk, Pond, Watermelon, Fire, Water, Lake, Mineral, or Extension. |

Palette accepts one of those 15 names and nothing else. Bind the property to a page variable or a Salesforce record field to pick the palette at runtime, and the value it holds must be a palette name: names are case-insensitive, and an empty or unrecognized value — a color such as `#0176d3` or `red` included — falls back to Aurora.

To draw a chart in colors of your own, use **Custom Palette** instead.

**Custom Palette**

Where Palette gives you one preset scheme or one brand color, Custom Palette lets you spell out the exact list of colors the chart cycles through. Click **Add Item** to append a color, then pick it from the color picker or type a value into it. Drag the handle on the left of a row to reorder, and use the **×** on the right to remove one.

Colors are applied to the series in the order they are listed: the first color goes to the first series, the second to the second, and so on. If the chart has more series than you listed colors, the list repeats from the start.

Custom Palette wins over Palette. As soon as it holds at least one color, the Palette selection is ignored; empty the list to hand control back to Palette.

Each entry is a hex code, such as `#0176d3` or, with an alpha channel, `#0176d3ff`. No shades are derived: what you list is exactly what is drawn. Entries that are not hex codes are dropped, and a list left with no color hands the chart back to Palette. Charts that use a single color, such as Gauge and Flat Gauge, take the first entry.

Note: when a chart displays several series — a grouped Column or Bar chart with multiple measures, a Donut, a Stacked Column — a single listed color draws every series in that one color. Supply as many colors as the chart has series to keep them distinguishable.

Use Custom Palette when the colors carry meaning and cannot be left to a preset — for example a Donut of opportunity stages where Closed Won must be green and Closed Lost red. Listing `#04844b`, `#c23934`, `#0176d3`, `#f28b00` gives those first two stages their expected colors and leaves the rest on brand blue and orange.

To change the colors without editing the component, toggle the property to variable mode and bind it to a Text Collection page variable instead of listing the values inline.

### Chart

Properties in the Chart group appear and disappear with the selected type, so they are grouped below by the types they belong to.

#### Bar, column and pyramid charts

| Property             | What it does                                                                                                               |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Show Values**      | Displays the numeric value on each bar, column or segment. Donut and Treemap charts have it too.                           |
| **Show Labels**      | Prints the group name inside each treemap rectangle. Treemap only.                                                         |
| **Normalize Values** | Normalizes stacked values so each stack sums to 100%, which makes proportions easy to compare. Stacked types only.         |
| **Axis Mode**        | Arranges multiple series: Single Axis (default), Dual Axis, or Small Multiples. Line, Combo and Metrics Radar have it too. |

#### Donut charts

| Property                               | What it does                                                                           |
| -------------------------------------- | -------------------------------------------------------------------------------------- |
| **Donut Center Size**                  | The size of the hollow center, from 0% to 100% in steps of 10. Default: 60%.           |
| **Show Percentages**                   | Labels each slice with its percentage of the total. Treemap charts have it too.        |
| **Show Total**                         | Displays the total in the center of the donut. Heatmap and Treemap charts have it too. |
| **Total Font Size**                    | Default, or 10 to 64. Requires **Show Total**.                                         |
| **Combine Small Groups into "Others"** | Merges the small slices into a single "Others" slice.                                  |
| **Donut Section Spacing**              | The gap between sections, in degrees, from 0 (default) to 10.                          |

#### Gauge charts

| Property                 | What it does                                                     |
| ------------------------ | ---------------------------------------------------------------- |
| **Show Band Value**      | Shows the numeric value on the band.                             |
| **Show Band Percentage** | Shows the percentage on the band.                                |
| **Show Band Range**      | Shows the minimum and maximum below the gauge.                   |
| **Show Band Label**      | Shows text labels on the colored bands.                          |
| **Gauge Angle**          | The sweep of the dial: 90°, 120°, 180°, 240° (default), or 270°. |
| **Gauge Indicator Type** | The pointer drawn against the dial: Needle (default) or Circle.  |
| **Hide Tick Values**     | Hides the numbers printed around the dial.                       |

#### Line, combo and radar charts

| Property                       | What it does                                                     |
| ------------------------------ | ---------------------------------------------------------------- |
| **Show Points**                | Draws a dot at each data point.                                  |
| **Show Values in Chart Lines** | Shows the numeric value at each data point. Line and Combo only. |

#### Flat gauge charts

Flat Gauge charts get their own **Flat Gauge Type** group, which decides how the bar is drawn.

| Property             | What it does                                                                                                                                                                     |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Type**             | Continuous (default) draws one solid bar, Discrete breaks it into steps, and Tiered colors it by the tier the value falls in.                                                    |
| **Number of Steps**  | How many steps a discrete gauge is cut into. Default: 5. Requires **Type** = Discrete. Too high a number and the steps stop being visible.                                       |
| **Flat Gauge Tiers** | The tiers themselves, each with a **Label**, a **Percentage** of the max range, and a **Color**. Requires **Type** = Tiered. For full coverage the percentages should total 100. |

Tiers color the filled part of the gauge only. They are not drawn as background bands behind the unfilled remainder.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FCWZyWJ0H2Lzrw64W18ya%2Fchart-flat-gauge-types.png?alt=media" alt="The three Flat Gauge Type variants"><figcaption><p>The same value drawn as a Continuous, a Discrete and a Tiered flat gauge</p></figcaption></figure>

### Range Values

Gauge and Flat Gauge only. This group sets the numeric scale of the dial.

| Property           | What it does                         |
| ------------------ | ------------------------------------ |
| **Min range**      | The bottom of the scale. Default: 0. |
| **Max Range**      | The top of the scale. Default: 100.  |
| **Show Min Range** | Displays the minimum as a label.     |
| **Show Max Range** | Displays the maximum as a label.     |

### X-Axis

Axis-based types only: Bar, Stacked Bar, Column, Stacked Column, Line, Pyramid, Stacked Pyramid, Combo and Metrics Radar.

| Property         | What it does                                                                                     |
| ---------------- | ------------------------------------------------------------------------------------------------ |
| **Hide X Axis**  | Hides the horizontal axis line and its tick marks.                                               |
| **Hide X Title** | Hides the label set in **X Title**, leaving the axis itself visible. Heatmap charts have it too. |

### Y-Axis

The same axis-based types as **X-Axis**.

| Property          | What it does                                                                                                                        |
| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| **Hide Y Axis**   | Hides the vertical axis line and its tick marks.                                                                                    |
| **Hide Y Title**  | Hides the label set in **Y Title**, leaving the axis itself visible. Heatmap charts have it too.                                    |
| **Use Log Scale** | Puts the vertical axis on a logarithmic scale instead of a linear one, which helps when the data spans several orders of magnitude. |

### Legend

Turn **Show Legend** on to display a key matching each color to its series. The settings below only apply once it is on.

| Property                      | What it does                                                                                          |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| **Position**                  | Where the legend sits: Left, Right (default), Top, or Bottom.                                         |
| **Show Header**               | Adds a title above the legend.                                                                        |
| **Display Inside Chart Area** | Places the legend inside the chart rather than beside it, which buys space when the chart is cramped. |
| **Reverse Item Order**        | Reverses the order of the legend entries.                                                             |

### Tooltip

Controls what appears when a user hovers over a chart element. Available for every type except Gauge and Flat Gauge.

| Property                    | What it does                                                |
| --------------------------- | ----------------------------------------------------------- |
| **Tooltip Show Dimensions** | Shows the grouping value, for example "Stage: Negotiation". |
| **Tooltip Show Measures**   | Shows the numeric value, for example "Amount: $50,000".     |
| **Tooltip Show Percentage** | Shows the percentage contribution.                          |

### Set Component Visibility

All components support conditional visibility — see [Component Visibility](/dynamic-components/core-concepts/component-visibility.md).

## Use Cases

### Quick Start: Opportunity Pipeline Chart

Build a chart showing open opportunities grouped by stage in under 5 minutes.

{% stepper %}
{% step %}

#### Create a new Dynamic Component

* Open the Avonni Dynamic Components App.
* Create a new component.
* From the component list on the left, drag **Chart** onto the canvas
  {% endstep %}

{% step %}

#### Configure the Data Source

* Select the component on the canvas.
* In the Properties Panel, set **Data Source** to **Query**.
* **Object**: Select `Opportunity`.
* **Filter**: `IsClosed = false` (to show only open opportunities)

> **Why**: This ensures the chart displays only active deals.
> {% endstep %}

{% step %}

#### Set the Chart Type

* In the Properties Panel, find **Type** and select **Bar**.
* This creates a horizontal bar chart by default.
  {% endstep %}

{% step %}

#### Configure Data Mappings

* Scroll to **Data Mappings** section.
* **Bars**: Click **Add** and set:
  * **Field**: `StageName`
  * **Group**: Leave blank
* **Bar Length**: Click **Add** and set:
  * **Field**: `Amount`
  * **Measures**: `Sum`

> **Why**: Bar Length tells the chart what values to measure (sum of opportunity amounts). Bars defines what to group by (stage).
> {% endstep %}

{% step %}

#### Add Labels and Legend

* Enable **Show Legend** (toggle on).
* Enable **Show Values** (toggle on) to display amounts on each bar.
* Set **Title**: "Open Pipeline by Stage"
* Set **Y Title**: "Stage" and **X Title**: "Amount ($)"

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2Fca7zbVryGBML5Ng6fdTx%2Fchart-example-bar.png?alt=media" alt="A bar chart of open pipeline by stage"><figcaption><p>The finished chart: one bar per open stage, each carrying its own total</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Revenue Share by Lead Source

See where the open pipeline comes from, using the same query and a different chart type.

{% stepper %}
{% step %}

#### Start from the same query

* Add a **Chart** to the canvas and select it.
* Set **Data Source** to **Query**, **Object** to `Opportunity`, and use the same `IsClosed = false` filter.
  {% endstep %}

{% step %}

#### Set the type, then look at Data Mappings again

* In the Properties Panel, find **Type** and select **Donut**.
* Reopen **Data Mappings**. The two slots have renamed themselves: what read **Bars** and **Bar Length** on the bar chart now read **Sliced By** and **Value**.

> **Why**: The slots do the same two jobs whatever they are called. One groups the records, the other measures them. Learn the pair once and every chart type follows.
> {% endstep %}

{% step %}

#### Configure Data Mappings

* **Sliced By**: **Field** `LeadSource`
* **Value**: **Field** `Amount`, **Measures** `Sum`
  {% endstep %}

{% step %}

#### Turn on the donut settings

* Leave **Donut Center Size** at 60%.
* Enable **Show Total** to print the grand total in the hollow center.
* Enable **Show Percentages** to label each slice with its share.
* Enable **Show Legend** (toggle on).
* Set **Title**: "Revenue share by lead source", and set **Palette** to **Ocean**.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2FnanX19BaIwBAG076QKr7%2Fchart-example-donut.png?alt=media" alt="A donut chart of revenue share by lead source"><figcaption><p>The same records grouped by lead source, with the total in the center</p></figcaption></figure>
{% endstep %}
{% endstepper %}

### Open Pipeline Against a Target

A gauge, the one type where the two-slot pattern does not apply: there is nothing to group.

{% stepper %}
{% step %}

#### Set the type to Gauge

* Add a **Chart**, set **Data Source** to **Query** on `Opportunity`, and use the same `IsClosed = false` filter.
* In the Properties Panel, find **Type** and select **Gauge**.
  {% endstep %}

{% step %}

#### Map the one slot there is

* Open **Data Mappings**. A gauge plots a single number, so it offers a **Value** slot and no grouping slot at all: there is no **Bars**, no **Sliced By**, nothing to put a category field into.
* **Value**: **Field** `Amount`, **Measures** `Sum`

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F5eoy6x6OnV7IxnXFnc5R%2Fchart-example-gauge-panel.png?alt=media" alt="The Chart panel on a gauge, showing a single Value mapping slot" width="320"><figcaption><p>On a gauge, Data Mappings offers a Value slot and no grouping slot beside it</p></figcaption></figure>
{% endstep %}

{% step %}

#### Give the dial its scale

* Open **Range Values** and set **Min range** to 0 and **Max Range** to your target, here 2000000.
* Enable **Show Band Value** to print the total under the needle.
* Set **Title**: "Open pipeline against target"

> **Why**: A gauge means nothing without a scale to read the value against, and that scale is not derived from your data. Leave Max Range at its default of 100 and a pipeline of 1.5M pins the needle at the top.

<figure><img src="https://2532358799-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FODPvvv7Cx9Z9RECLn3oV%2Fuploads%2F8T18tVS9WlWlyEQsKO2V%2Fchart-example-gauge.png?alt=media" alt="A gauge chart of open pipeline against a target"><figcaption><p>The finished gauge: 1.5M of open pipeline read against a 2M target</p></figcaption></figure>
{% endstep %}
{% endstepper %}

## Styling

Configure the Chart's appearance from the **Style** tab of the Edit Chart panel.

{% tabs %}
{% tab title="Margin" %}
Controls the *outer* spacing around the chart.

* **Top / Right / Bottom / Left:** Adjust the space on each side.
  {% endtab %}

{% tab title="Padding" %}
Controls the *inner* spacing between the chart and its border.

* **Top / Right / Bottom / Left:** Adjust the inner spacing on each side.
  {% endtab %}

{% tab title="Size" %}
Controls the chart's dimensions.

* **Width / Height:** Set fixed dimensions for the chart.
* **Min Width / Max Width / Min Height / Max Height:** Constrain the size within bounds.
* **Overflow:** Control how content that exceeds the bounds is handled.
* **Overflow X / Overflow Y:** Control overflow per axis.
  {% endtab %}

{% tab title="Border" %}
Customizes the border surrounding the chart.

* **Color / Size / Style / Radius:** Set the border color, thickness, style, and corner rounding.
  {% endtab %}

{% tab title="Gauge Chart Style" %}
Appears only when **Type** is Gauge.

* **Circle Indicator Color:** The color of the circle indicator on the dial.
  {% endtab %}
  {% endtabs %}

## Troubleshooting Common Issues

* **Chart shows "No Data" or is blank** — The query filter may be too restrictive, or no records match the criteria. Check the filter condition in a Report or via SOQL, verify that the Bars and Bar Length fields exist on the selected object and contain values, and confirm the page variable is populated before the Chart renders if using a variable data source.
* **Chart shows unexpected colors or grouping** — In Data Mappings, confirm Bars and Bar Length are set to the correct fields. If Combine Small Groups into "Others" is enabled, small donut slices are merged — disable it to see all individual groups.
* **The gauge shows an incorrect range** — Check Min Range and Max Range in the Range Values section. For a win-rate gauge (0–100%), set Min Range to 0 and Max Range to 100. Use Show Min Range / Show Max Range to display those values as labels on the gauge.
* **Legend overlaps or takes up too much space** — Enable Display Inside Chart Area to move the legend into the chart space, or enable Reverse Item Order if space is still tight. Increasing the component container size on the page also helps. For donuts, enable Combine Small Groups into "Others" to reduce the number of legend entries.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.avonnicomponents.com/dynamic-components/components/chart.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.