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.

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 #

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.

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.

Appearance #

Collapsed by default, summarised as Colors, axes, legend. Nothing in it is required.

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.

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 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).
• 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 #

Collapsed by default, summarised as KPI summary tiles above the chart. Select Add highlight to add one.

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.

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

Chart controls on the page #

Two 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.
• Download chart as image saves the chart as it is currently drawn.

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.