> For the complete documentation index, see [llms.txt](https://docs.appfarm.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appfarm.io/how-to/user-interface/understand-charts.md).

# Understand charts

Let's take a look at the most important [chart component](/library/ui-components.md#basic-charts) properties.

Each chart is bound to a single data source from which it extracts data. There is one exception: the [Advanced combined chart](/library/ui-components/advanced-combined-chart.md).

Most charts are based on three properties: **Category Property**, **Value Property,** and **Dataset Property**. Some advanced charts use **X Value** and **Y Value** instead of the category and value properties.

**Category Property** corresponds to the x-axis, and **Value Property** to the y-axis of a chart. As indicated by the names, the category holds the categories or groups, whereas the value contains the values for each category or group.

For example, if you were to specify only **Category Property**, the count of entries for each category or group would be displayed. By setting a **Value Property**, the value of each **Category Property** group is displayed.

You can set an **Aggregation Function**, such as `Sum` or `Average`, in order to calculate and display the values in a meaningful way per category. If no function is selected, the count of entries for each category will be displayed.

The data is treated as a single dataset when using a **Category Property** and **Value Property**. A dataset is a collection of data that consists of two columns (category and value) and many rows. In a line chart, this would be represented as a single line. By selecting a **Dataset Property**, an extra dimension is added, and the dataset is segmented into multiple datasets. In a line chart, this would be represented as multiple lines.

To improve readability when a dataset is segmented into multiple datasets, you can select **Stack Datasets** to create some separation between the lines and make the data easier to interpret.

{% tabs %}
{% tab title="Chart average temperatures in different cities per month" %}
You have an object class called `Climate` with three properties `Month`, `Temperature` and `City`.

**Single dataset**

Bind `Month` to **Category Property**, `Temperature` to **Value Property** and select `Average` for **Aggregation Function**. For each month, the average temperature of all cities will be calculated and displayed.

**Multiple datasets**

Bind `Month` to **Category Property**, `Temperature` to **Value Property,** and `City` to **Dataset Property**. Select `Average` as **Aggregation Function**. For each city, the average temperature for each month is calculated and displayed.
{% endtab %}
{% endtabs %}

## Respond to clicks with On Series Click

Charts can run an action when a user clicks a bar, point, or bubble. Add an action to the **On Series Click** event handler, found under **Event Handlers** in the chart's properties. The event fires once per click, on the single data point that was clicked.

On Series Click is available on the Advanced bar, line, bubble, scatter, heatmap, and combined charts, and behaves the same way on each.

The event exposes the clicked point's values, listed below. To use them, add an action param to the action for each value you want, set its data type to match the value it receives, and bind the event output to it. If a param's data type does not match the event output, the output will not be available to select.

| Value     | Data type                                                                                                                                                                                                       | Description                                                                                                                                         |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Serie** | String                                                                                                                                                                                                          | The name of the clicked dataset.                                                                                                                    |
| **X**     | Matches the bound **Category Property** (or **X Value**)                                                                                                                                                        | The clicked point's category value.                                                                                                                 |
| **Y**     | Depends on the chart. See below.                                                                                                                                                                                | The clicked point's value as shown in the chart. On charts with an **Aggregation Function**, this is the aggregated value for the clicked category. |
| **Z**     | Matches the bound **Bubble Size** ([Advanced bubble chart](/library/ui-components/advanced-bubble-chart.md)) or **Value Property** ([Advanced heatmap chart](/library/ui-components/advanced-heatmap-chart.md)) | The clicked point's size or value. Only available on these two charts.                                                                              |

The data type of **Y** depends on the chart and its settings:

* On the [Advanced bar](/library/ui-components/advanced-bar-chart.md), [line](/library/ui-components/advanced-line-chart.md), and [combined](/library/ui-components/advanced-combined-chart.md) charts with an **Aggregation Function**:
  * `Count`, or no **Value Property** bound: Integer.
  * `Average` or `Median`: Float.
  * `Sum`, `Min`, or `Max`: matches the bound **Value Property**.
* On the Advanced bar, line, and combined charts with a Datetime **Category Property** that isn't grouped by a date unit: matches the bound **Value Property**.
* On the Advanced scatter, bubble, and heatmap charts: matches the bound **Y Value**. If **Y Value** is an enum, **Y** is an Integer holding the position of the clicked category on the axis, not the enum value.

On the Advanced combined chart, the data types are taken from the first dataset.

{% hint style="info" %}
**Good to know**

For a Datetime **Category Property**, **X** holds a date value, not the category's position on the axis. When categories are grouped by a date unit, such as month, **X** is the start of the clicked period in the user's time zone, for example the first day of the month at 00:00. Clicking the group for objects without a category value gives an empty **X**.
{% endhint %}

{% tabs %}
{% tab title="Open detail for the clicked category" %}
A bar chart shows order totals per month. You want a click on a bar to open a dialog listing that month's orders.

Add an **On Series Click** action. On it, create an action param with the same data type as the month category to receive **X**, then use that param to filter the dialog's data source to the clicked month.
{% endtab %}
{% endtabs %}

## Respond to zoom with On Zoom <a href="#user-content-respond-to-zoom-with-on-zoom" id="user-content-respond-to-zoom-with-on-zoom"></a>

The Advanced line chart and Advanced combined chart can run an action when the user zooms along the x-axis. Set **Zoom Type** to `X Axis` or `XY Axis`, then add an action to the **On Zoom** event handler under **Event Handlers**.

The event exposes the zoomed range of the x-axis:

| Value          | Data type                                                                                       | Description                    |
| -------------- | ----------------------------------------------------------------------------------------------- | ------------------------------ |
| **X Axis Min** | Matches the bound **Category Property** (or **X Value**). Float on the Advanced combined chart. | The start of the zoomed range. |
| **X Axis Max** | Matches the bound **Category Property** (or **X Value**). Float on the Advanced combined chart. | The end of the zoomed range.   |

For categories that aren't dates, **X Axis Min** and **X Axis Max** hold the categories just outside the zoomed range, so a filter using them includes every visible category.

{% hint style="info" %}
**Good to know**

When a Datetime **Category Property** is grouped by a date unit, such as month, **X Axis Min** and **X Axis Max** are approximate dates. Don't rely on them falling exactly on the start of a period.
{% endhint %}


---

# 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.appfarm.io/how-to/user-interface/understand-charts.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.