---
title: Widget
description: Display a figure, a chart, or both, with the context that reads them.
---

A widget composes a context around a stat, a chart, or both. The context is the
widget's own data: a title, a description, a footnote that reads the data, and a
caption. It draws wherever the widget draws, alone or in a group.

A widget needs a stat, a chart, or both. The SDK refuses a widget with neither.

## API

```ts
widget(): WidgetBuilder
```

| Method           | Input                                      | Result                                     |
| ---------------- | ------------------------------------------ | ------------------------------------------ |
| `setTitle`       | `string`, `{ icon?: string }`              | Names the widget, with an optional icon.   |
| `setDescription` | `string`                                   | Adds a neutral line under the title.       |
| `setStat`        | `StatInput`                                | Sets the figure. Replaces the stat.        |
| `setChart`       | `Nodeable<Chart>`                          | Sets the chart. Replaces the chart.        |
| `setFootnote`    | `string`, `{ icon?: string; tone?: Tone }` | Adds the reading of the data, with a tone. |
| `setCaption`     | `string`                                   | Adds a muted line under the footnote.      |

Properties that you do not set are not included in the protocol output.

## Basic widget

A stat is a number and the number field that formats it. The renderer formats
the value in the client's locale, so the same widget reads correctly for every
user.

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

## The stat

`setStat` takes an object that mirrors the stat on the wire.

| Property          | Input                                                       | Result                                                       |
| ----------------- | ----------------------------------------------------------- | ------------------------------------------------------------ |
| `value`           | `number`                                                    | The figure. Required.                                        |
| `field`           | `NumberFieldBuilder`                                        | Formats the value, the prior, and the change. Required.      |
| `prior`           | `number`                                                    | The value of the prior period.                               |
| `delta`           | `"percent" \| "absolute"`                                   | How the change from the prior is stated. Default `absolute`. |
| `tone`            | `"neutral" \| "info" \| "success" \| "warning" \| "danger"` | The meaning of the figure.                                   |
| `description`     | `string`                                                    | A line under the value that reads the figure.                |
| `descriptionIcon` | `string`                                                    | An icon name beside the description.                         |

A currency field must carry its currency code. A stat has no row to read a
per-record currency from.

### Change from a prior

When you set a prior, the renderer computes the change and draws it beside the
value. `percent` states the change as a percent of the prior. `absolute` states
the difference through the field, which on a percent field is points. A prior of
zero draws no change. The sign of a change is not a meaning, so you set the tone.

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

### Tone

Use a tone to give semantic meaning to the figure. The renderer controls the
color and other visual details.

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

### Description

Add a description to explain the value or compare it with another period.

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

The description can include a separate icon name.

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

## The chart

`setChart` takes a chart builder from `charts`. A chart draws inside the widget,
under the stat when both are set.

### Spark area

A spark area chart shows a trend without axes or tooltips. Pass records to
`charts.sparkArea(data)`. Use `setFields` to select `x` and one or more number
fields in `series`.

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

### Bar list

A bar list ranks rows by one number field. Use `setFields({ label, value })`
to select the label field and the number field.

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

### Line chart

A line chart plots a value over an axis, one point per row and one line per
series. The `x` field places each row on the axis and the `series` are number
fields, each drawn in the theme's chart colour of its index. The ticks, the
tooltip, and the legend all read from the fields.

`setOptions` takes `showXAxis`, `showYAxis`, `showGridLines`, `showLegend`, each
true by default, and `curveType`: `linear`, `monotone`, or `step`. `onClick`
takes a link target, the same as a table row, and a click on a point follows it.

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

## The context

The title, the description, the footnote, and the caption frame the data. The
footnote reads the data, a trend or a comparison, and takes a tone. The caption
is a muted line for the range or an exclusion.

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

## Title icon

Set an icon name for the renderer to show beside the title. The protocol
contains the icon name, not an image or a glyph.

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

## All options

The context, the stat with a change, and a chart on the same widget.

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

See [Charts](/reference/widgets/charts) for all chart options and category bars.