---
title: Chart widget
description: "Use the **Chart widget** to summarise a dataset as a picture -- how many objects fall into each status, how a total moves month by month, how two measures compare. ![](https://auclio.com/wp-content/uploads/2026/09/Charts-1024x580.png) ## When to use it A Chart widget answers…"
url: "https://auclio.com/documentation/chart-widget/"
updated: "2026-11-10"
category: Widgets
---

# Chart widget

Use the **Chart widget** to summarise a dataset as a picture -- how many objects fall into each status, how a total moves month by month, how two measures compare.

![](https://auclio.com/wp-content/uploads/2026/09/Charts-1024x580.png)

## When to use it

A Chart widget answers a question about a whole dataset rather than showing its rows. Use it for:

- a count of objects by status, owner, or country;
- a total or average over time, bucketed by month or quarter;
- two measures side by side, or one against a second axis;
- a summary band at the top of a page, above the table that holds the detail.

Where users need the underlying objects, use a Table widget. Where a single number is the whole point, use a Card widget.

## Add a Chart widget

To add a Chart widget:

1. Open the page and enable **Layout edit mode**.
2. Select **Add a widget**.
3. Select the **Chart** tile, or drag it onto the page.
4. Enter a **Widget Title** and choose a **Chart type**.
5. Choose a **Dataset**, add at least one value, and choose a category field.
6. Select **Create**.
7. Save the page layout.

A chart needs three things before it will save: a dataset, at least one value, and a category field. Everything else has a working default.

## Configuration

The dialog is arranged in three tabs: **Data**, which holds everything a chart needs before it will save, **Appearance**, and **Highlights**. The preview stays visible below whichever tab is open.

### Basic Information

**Widget Title** is required. Unlike the Card widget, the chart can show it: the field carries a visibility control, and the title is shown by default. **Description** is optional and hidden by default, with its own visibility control.

### Chart type

Six types are available: **Bar**, **Horizontal bar**, **Line**, **Area**, **Pie**, and **Doughnut**. It defaults to **Bar**.

**Pie and Doughnut charts show a single value.** The dialog says so and refuses to add a second one. If you need to compare two measures, use a bar, line, or area chart.

### Dataset

Required. Choose the data type the chart summarises. Changing it clears the values and the category field, because both name properties of the old one.

### Values

A value is one measurement the chart draws. Each has a **Function** -- **Count**, **Sum**, **Average**, **Min**, or **Max** -- and, for everything except Count, a **Field**.

**Count** needs no field: it counts objects. The other four offer only Integer and Decimal properties, and if the data type has none the field explains *No numeric fields on this dataset*.

Select **Add value** for a second series. Bar, horizontal bar, line, and area charts can carry several; pie and doughnut carry exactly one.

### Group by

**Category field** is the property the chart groups on, and it is required. Any property can be used except Time, which is stored as free text and cannot be grouped reliably.

**Bucket by** appears only when the category field is a Date or a DateTime, and offers **Day**, **Week**, **Month**, **Quarter**, and **Year**. It defaults to **Day**, which for anything but a short-lived dataset is rarely what you want — set it to **Month** or **Quarter** unless you have a reason not to.

**Week** buckets begin on the first day of the week chosen by **the person reading the page**, under **First Day of Week** in their **Locale & Region** settings, so a user who starts the week on Sunday sees the same records divided differently from one who starts it on Monday. Weeks are labelled by ISO week number, such as `W52 2025` and `W1 2026`, whichever day they start on. See [Navigate the Auclio interface](https://auclio.com/documentation/auclio-interface/) for detailed instructions on user settings.

Objects with no value in the date field are gathered into a final **(No date)** group, which always comes last.

**Max categories** limits how many groups are drawn, between 1 and 200. It is optional, but see *Limits worth knowing* below before leaving it empty. On a date grouping it keeps the most recent periods, and the chart says so with a caption such as *Latest 12 of 30 periods*.

### Appearance

The **Appearance** tab. Nothing in it is required.

**Colours** chooses how the chart is coloured: **Palette**, the default, or **Highlight a value**, described below.

**Color palette** sets the colours every series or slice takes by default. The options are **Default**, which follows the application’s theme colours, **Monochrome**, **Vibrant**, **Cool**, **Warm**, **Earth**, and **Pastel**, each shown with a strip of its colours. **Monochrome** draws every series in shades of one colour and adds two settings: **Base colour**, the colour the shades are generated from, which defaults to the theme colour, and **Shade spread**, a slider from **Subtle** to **Distinct** that sets how far apart the shades are. Every palette stays legible in dark mode.

A colour you set on an individual series or slice overrides the palette. **Reset colours** clears those individual colours, so the chart takes all its colours from the palette again; it is unavailable while nothing has been overridden.

**Series styling** gives each value a **Series label**, a **Draw as** setting of **Bar**, **Line**, or **Area**, and a **Color**. With two or more values each one also gets **Plot on 2nd axis**, which is how you chart a count against a currency total without the smaller series flattening. The last series still on the primary axis cannot be moved across, because an axis with nothing on it has no scale.

For pie and doughnut charts this section becomes **Slice colors** instead, with one swatch per category.

**Highlight a value** draws the values that matter in a **Main colour** and everything else in a muted tone of it, so the eye goes straight to them. It works on a chart with a single value; with two or more it is unavailable, and a chart already set to it falls back to the palette and says so. **Highlight** decides which values are drawn at full strength:

- **Highest value** or **Lowest value**;
- **Latest value** — the most recent period, which suits a chart grouped by date;
- **Specific category** — the one you choose under **Category**;
- **Compared to a threshold** — values **Above** or **Below** the **Threshold** you enter;
- **Compared to the average** — values **Above** or **Below** the chart’s average.

**Reference line** adds a dashed line across the chart in the main colour, at the **Average** or at a **Custom value** entered in **Line value**; pie and doughnut charts have no reference line. **Label highlighted values**, on by default, prints the number on each highlighted value. While a bar, line, or area chart highlights a value its legend is switched off, and the series styling has no colour, because the colours carry the highlight.

**Axis titles** sets **Category axis title** and **Value axis title**. Both take the field name as their placeholder, so leaving them empty labels the axes sensibly. The eye icon beside each hides that title. When a series is plotted on the second axis, the value field splits into **Primary value axis title** and **Secondary value axis title**.

**Legend & labels** sets **Legend position** — **Bottom**, **Top**, **Left**, or **Right**, defaulting to Bottom — and **Show legend**, which is on. Pie and doughnut charts add **Slice labels**, which names each category next to its slice independently of the legend. **Value labels** decides whether the numbers are printed on each bar, point, or slice: **Off**, **Auto (declutter)**, the default, which leaves out numbers that would collide, or **All (show every value)**.

**Value format** adds a **Prefix** or a **Suffix** to every number the chart prints, for a currency symbol or a percent sign.

**Categories & axis** holds the rest:

- **Sort categories** — **Default (as returned)**, **Value (high → low)**, **Value (low → high)**, **Label (A → Z)**, or **Label (Z → A)**. When the category field is a Date or a DateTime the options are **Chronological (oldest → newest)**, the default, **Chronological (newest → oldest)**, and the two value sorts instead, because sorting periods by their label put them out of date order. Charts saved before 26.9 with **Default (as returned)** or **Label (A → Z)** on a date field now read oldest first, and those with **Label (Z → A)** newest first. Whatever the sort, the **(No date)** group stays last.
- **Stack bars** — bar and horizontal bar charts only, and only with at least two values. Stacks the series on top of one another so the category total is readable, rather than side by side.
- **Start at zero** — on by default. Switch it off only when the interesting variation is small relative to the values, and say so in the widget description, because a truncated axis exaggerates differences.
- **Axis min**, **Axis max**, and **Axis step** — each is Auto when empty.

### Highlights

The **Highlights** tab adds KPI summary tiles above the chart. Select **Add highlight** to add one. These tiles are separate from **Highlight a value** on the **Appearance** tab, which changes the chart’s colours rather than adding tiles.

**Highlights are computed from what the chart displays, not from the whole dataset.** If **Max categories** is set to 5, **Total** is the sum of those five bars. This is deliberate — a tile that disagreed with the picture beneath it would be worse — but it is the single thing people get wrong about this section.

Each highlight has:

- **Metric** — **Total**, **Average (per category)**, **Highest**, **Lowest**, or **Categories**;
- **Value** — which series it reads, needed by every metric except Categories;
- **Label** — the caption above the number;
- an optional colour, which falls back to the default below.

Once at least one highlight exists, three settings apply to all of them: **Tile style**, either **Minimal (inline)** or **Card tiles**; **Alignment**, one of **Left**, **Center**, **Right**, **Space between**, **Space around**, or **Space evenly**; and a **Default color**.

### Preview

The dialog draws the chart as you configure it, and it is worth using — the interaction between chart type, number of series, stacking, and axis settings is much easier to judge by eye. When the configuration matches nothing, the preview reads *No data matches this configuration*.

The preview is drawn at the dialog’s size, and a chart’s labels, legend, and spacing fit differently at other sizes. **Expand preview**, available once the configuration is complete, opens the chart in a window you can drag to resize, to check how it renders at phone, tablet, and desktop widths.

On the page itself, a chart with nothing to draw reads *No data to display*.

## Chart controls on the page

These controls appear on the widget’s toolbar, for every user and not only in edit mode:

- **Show values** and **Hide values** prints the number on each bar, point, or slice, and removes it again. It overrides **Value labels** for the person using it, for as long as the page is open, and changes nothing for anyone else.
- **Download chart as image** saves the chart as it is currently drawn.
- **Refresh widget data** reloads the chart from its dataset.

## Sizing on the grid

A Chart is added twenty rows tall, spanning the full width on a phone or a small tablet and half the grid on a large screen. It can be narrowed to three columns on a desktop-width screen, and to two on a phone. Give it the height -- axis labels and a legend squeezed into a short cell leave very little room for the plot.

**A Chart can only go in a page's main area.** Like the Table, Text Grid, and Form widgets, it cannot be added to a header or a footer.

## Limits worth knowing

Two ceilings apply to every chart, and both are visible to users rather than internal.

**A chart that takes more than 10 seconds to calculate returns an error rather than waiting.** On a large data type, group on a property with few distinct values, or set **Max categories**.

**A chart shows at most 200 categories, and 50 when Max categories is empty.** This is the usual explanation for a chart that appears to be missing groups: the dataset has more than 50 distinct values in the category field, and the chart is showing 50 of them. Set **Max categories** explicitly whenever the number of groups matters.

## Recommendations

When using Chart widgets:

- group on a property with a manageable number of distinct values, and set **Max categories** when it might not be;
- set **Bucket by** to **Month** or **Quarter** for anything covering more than a few weeks;
- leave **Start at zero** on unless you have a reason to switch it off, and explain that reason in the widget description;
- use **Plot on 2nd axis** rather than dropping a series whose scale does not match;
- keep highlights to two or three, and label them so it is clear they describe the chart rather than the whole dataset;
- put the chart above the Table widget that holds the same data, so a user who wants the rows does not have to navigate to find them.