Charts

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.

import {
  charts,
  defineResource,
  fields,
  widget,
} from '@backlit/sdk'

const orders = defineResource('orders', [])

const sources = [
  { source: 'Search', count: 412 },
  { source: 'Referral', count: 231 },
  { source: 'Direct', count: 128 },
]

orders.view('overview', () =>
  widget()
    .setTitle('Orders by source')
    .setChart(
      charts.barList(sources).setFields({
        label: fields.text('source', { label: 'Source' }),
        value: fields.number('count', {
          label: 'Orders',
          format: 'integer',
        }),
      })
    )
)

export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "overview",
    "slots": {
      "content": [
        {
          "kind": "widget",
          "title": "Orders by source",
          "chart": {
            "kind": "bar-list",
            "fields": {
              "label": {
                "kind": "text",
                "name": "source",
                "label": "Source"
              },
              "value": {
                "kind": "number",
                "name": "count",
                "format": "integer",
                "label": "Orders"
              }
            },
            "data": [
              {
                "source": "Search",
                "count": 412
              },
              {
                "source": "Referral",
                "count": 231
              },
              {
                "source": "Direct",
                "count": 128
              }
            ]
          }
        }
      ]
    }
  }
}

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.

import {
  charts,
  defineResource,
  fields,
  widget,
} from '@backlit/sdk'
const orders = defineResource('orders', [])
orders.view('overview', () =>
  widget()
    .setTitle('Paid orders')
    .setChart(
      charts
        .line([
          { day: 'Mon', paid: 30 },
          { day: 'Tue', paid: 40 },
        ])
        .setFields({
          x: fields.text('day'),
          series: fields.number('paid', {
            label: 'Paid orders',
          }),
        })
        .setOptions({
          showLegend: false,
          curveType: 'monotone',
        })
    )
)
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "overview",
    "slots": {
      "content": [
        {
          "kind": "widget",
          "title": "Paid orders",
          "chart": {
            "kind": "line",
            "fields": {
              "x": {
                "kind": "text",
                "name": "day",
                "label": ""
              },
              "series": [
                {
                  "kind": "number",
                  "name": "paid",
                  "label": "Paid orders"
                }
              ]
            },
            "options": {
              "showLegend": false,
              "curveType": "monotone"
            },
            "data": [
              {
                "day": "Mon",
                "paid": 30
              },
              {
                "day": "Tue",
                "paid": 40
              }
            ]
          }
        }
      ]
    }
  }
}

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.

import {
  charts,
  defineResource,
  fields,
  widget,
} from '@backlit/sdk'
const orders = defineResource('orders', [])
orders.view('overview', () =>
  widget()
    .setTitle('Paid orders')
    .setChart(
      charts
        .sparkArea([
          { day: 'Mon', paid: 30 },
          { day: 'Tue', paid: 40 },
        ])
        .setFields({
          x: fields.text('day'),
          series: fields.number('paid', {
            label: 'Paid orders',
          }),
        })
        .setOptions({
          fill: 'solid',
          curveType: 'monotone',
        })
    )
)
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "overview",
    "slots": {
      "content": [
        {
          "kind": "widget",
          "title": "Paid orders",
          "chart": {
            "kind": "spark-area",
            "fields": {
              "x": {
                "kind": "text",
                "name": "day",
                "label": ""
              },
              "series": [
                {
                  "kind": "number",
                  "name": "paid",
                  "label": "Paid orders"
                }
              ]
            },
            "options": {
              "fill": "solid",
              "curveType": "monotone"
            },
            "data": [
              {
                "day": "Mon",
                "paid": 30
              },
              {
                "day": "Tue",
                "paid": 40
              }
            ]
          }
        }
      ]
    }
  }
}

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.

import {
  charts,
  defineResource,
  fields,
  widget,
} from '@backlit/sdk'
const orders = defineResource('orders', [])
orders.view('overview', () =>
  widget()
    .setTitle('Paid orders')
    .setChart(
      charts
        .categoryBar({ paid: 70, unpaid: 30 })
        .setFields({
          values: [
            fields.number('paid', { label: 'Paid' }),
            fields.number('unpaid', { label: 'Unpaid' }),
          ],
        })
        .setOptions({
          legendLayout: 'horizontal',
          marker: { value: 60, tooltip: 'Target' },
        })
    )
)
export default orders

{
  "kind": "success",
  "status": 200,
  "node": {
    "kind": "view",
    "resource": "orders",
    "name": "overview",
    "slots": {
      "content": [
        {
          "kind": "widget",
          "title": "Paid orders",
          "chart": {
            "kind": "category-bar",
            "fields": {
              "values": [
                {
                  "kind": "number",
                  "name": "paid",
                  "label": "Paid"
                },
                {
                  "kind": "number",
                  "name": "unpaid",
                  "label": "Unpaid"
                }
              ]
            },
            "options": {
              "legendLayout": "horizontal",
              "marker": {
                "value": 60,
                "tooltip": "Target"
              }
            },
            "data": {
              "paid": 70,
              "unpaid": 30
            }
          }
        }
      ]
    }
  }
}

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.