---
title: Charts
description: Build bar lists, lines, spark areas, and category bars.
---

Use `charts` to create a chart and pass it to `widget().setChart(chart)`.
Charts are not standalone view blocks. Declare the fields that read the data.
Only selected fields are sent. Number fields determine value formatting.

## Bar list

`charts.barList(rows).setFields({ label, value })` displays one bar per row.
`value` is one number field. `setOptions({ sortOrder })` accepts `ascending`,
`descending`, or `none`. The default display order is descending.
`setColor(colorOrCallback)` selects a chart color token, from `1` through `5`.
A callback can return `undefined` for the default color.
`onClick(linkTo(...))` sets a target for each row.

<BacklitExample path="widgets/widget/bar_list" view="overview" />

## Line

`charts.line(rows).setFields({ x, series })` draws one line per number field.
`series` accepts one number field or an array. Rows retain their input order.
A date field on `x` supplies a time axis. Text, enum, and number fields can also
supply axis values. `onClick(linkTo(...))` sets point targets.

<BacklitExample path="charts/line" view="overview" />

`setOptions` accepts these options:

| Option                                                                 | Default or values                                                  |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `showXAxis`, `showYAxis`, `showGridLines`, `showLegend`, `showTooltip` | `true`                                                             |
| `startEndOnly`, `autoMinValue`, `connectNulls`                         | `false`                                                            |
| `intervalType`                                                         | `equidistantPreserveStart` or `preserveStartEnd`; first is default |
| `minValue`                                                             | `0`                                                                |
| `maxValue`                                                             | Largest value                                                      |
| `curveType`                                                            | `linear`, `monotone`, or `step`; `linear` is default               |

`connectNulls` draws a line over missing values. Without it, missing values
leave gaps. `autoMinValue` fits the lower bound to the data.

## Spark area

`charts.sparkArea(rows).setFields({ x, series })` draws a small trend chart.
It has no axes, legend, tooltip, or click target. Give the first series a label
for the accessible chart name.

<BacklitExample path="charts/spark_area" view="overview" />

Options are `fill` (`gradient`, `solid`, or `none`; default `gradient`),
`curveType`, `autoMinValue`, `minValue`, `maxValue`, and `connectNulls`.
The last five options use the same defaults as the line chart.

## Category bar

`charts.categoryBar(record).setFields({ values })` shows parts of one total.
It accepts one record. `values` is an array of number fields. Field order
sets segment order. Field labels name the segments; the first field's format
formats all numbers.

<BacklitExample path="charts/category_bar" view="overview" />

`setOptions` accepts `showLabels` (default `true`), `legendLayout`
(`vertical` by default, or `horizontal`), and `marker: { value, tooltip? }`.
The marker value uses the data unit. Category bars have no click target.

## Validation and defects

Each chart requires its selected fields before it can produce a node. A line
or spark area needs at least one series. A category bar needs at least one
value field. Chart builders support `onDefect(reporter)` for invalid data.
Invalid structure throws; invalid data is reported and omitted.