Error bar

An error bar draws a center value and a whisker from a low to a high. The center is a point, or a bar from zero. The whisker is the uncertainty. The type is errorbar.

When to use it

Use an error bar when each category has a center and a range around it. Lab measurements is three assays, each a mean with a whisker. Dish means uses a bar for the mean and a whisker for the three runs. Salt, Monday to Friday follows one dish across the week, one point per day.

Use a range bar when the span itself is the mark and there is no center. Use a scatter when both axes are quantitative and each row is a point in that plane. Use a bar when you only have the amount.

Error bar, range bar, and scatter

A range bar floats from low to high. The rectangle is the span. It does not start at zero, and it has no center dot. An error bar always has a center at encoding.y. The whisker runs from low to high around that center. With mark.error set to bar, the bar grows from zero to y and the whisker is drawn on top of it.

A scatter places each row by two quantitative fields. Color and size can add more. It does not draw a whisker from a low and a high. An error bar keeps categories on x and one center on y. errorbars repairs to errorbar.

Data

Each row is one category, a center, and a range. encoding.x is the category. encoding.y is the center. encoding.low and encoding.high are the whisker ends. Lab measurements names mean, lo, and hi.

encoding.low and encoding.high
{
  "encoding": { "x": "assay", "y": "mean", "low": "lo", "high": "hi" }
}

encoding.error is the other shape. The field is a ± half-width around y. A mean of 140 and a delta of 2 draw a whisker from 138 to 142. encoding.low and encoding.high override it when both are set.

encoding.error
{
  "encoding": { "x": "assay", "y": "mean", "error": "delta" }
}

Columns named low, lo, or min, and high, hi, or max, are found when those keys are omitted. Name them on a first chart. A missing end skips the whisker and still draws the center.

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart. The chart loads from @chartkitdev/core/charts/errorbar, in @chartkitdev/core/extra. createRenderer([line]) does not include it.

A spec that renders

This is the smallest error bar. version, type, and a11y.alt are required. Three assays. The anchor is a point, so mark can be omitted. The whisker uses lo and hi.

spec.json
{
  "version": "1",
  "type": "errorbar",
  "data": [
    {
      "assay": "Control",
      "mean": 18.2,
      "lo": 17.1,
      "hi": 19.3
    },
    {
      "assay": "Batch A",
      "mean": 21.4,
      "lo": 20.6,
      "hi": 22.2
    },
    {
      "assay": "Batch B",
      "mean": 16.7,
      "lo": 15.3,
      "hi": 18.1
    }
  ],
  "encoding": {
    "x": "assay",
    "y": "mean",
    "low": "lo",
    "high": "hi"
  },
  "a11y": {
    "alt": "Batch A is highest, with a whisker from 20.6 to 22.2."
  }
}

Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.

Import@chartkitdev/core/charts/errorbarBundle@chartkitdev/core/extraFamilyLibrary
React
npm install @chartkitdev/core
npm install @chartkitdev/react

import { Chart } from "@chartkitdev/react";

export function Panel() {
  return <Chart spec={spec} />;
}
Vanilla
npm install @chartkitdev/core
npm install @chartkitdev/vanilla

import { mount } from "@chartkitdev/vanilla";

const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);
Vue
npm install @chartkitdev/core
npm install @chartkitdev/vue

<script setup>
import { Chart } from "@chartkitdev/vue";
</script>

<template>
  <Chart :spec="spec" />
</template>
Svelte
npm install @chartkitdev/core
npm install @chartkitdev/svelte

<script>
  import { Chart } from "@chartkitdev/svelte";
</script>

<Chart {spec} />
Astro
npm install @chartkitdev/core
npm install @chartkitdev/astro

---
import { Chart } from "@chartkitdev/astro";
---

<Chart spec={spec} />
Solid
npm install @chartkitdev/core
npm install @chartkitdev/solid

import { Chart } from "@chartkitdev/solid";

export function Panel() {
  return <Chart spec={spec} />;
}
Qwik
npm install @chartkitdev/core
npm install @chartkitdev/qwik

import { component$ } from "@builder.io/qwik";
import { Chart } from "@chartkitdev/qwik";

export const Panel = component$(() => {
  return <Chart spec={spec} />;
});
Angular
npm install @chartkitdev/core
npm install @chartkitdev/angular

import { Component } from "@angular/core";
import { Chart } from "@chartkitdev/angular";

@Component({
  standalone: true,
  imports: [Chart],
  template: `<ck-chart [spec]="spec" />`,
})
export class Panel {
  spec = spec;
}
Custom element
npm install @chartkitdev/core
npm install @chartkitdev/element

import "@chartkitdev/element";

const chart = document.querySelector("chart-kit");
chart.spec = spec;

Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.

Examples

The rail switches among existing error bar specs. Lab measurements is the gallery and core chart: points, and a whisker from low to high. Dish means is the bar anchor from the Salt assay showcase. Salt, Monday to Friday is the same dish as points, with mark.pointSize set to 5.

Anchor

mark.error is point or bar. Omit it, or set point, and each category is a marker at y. bar draws a bar from zero to y and keeps the whisker. The domain includes zero, so the bar has a baseline. Dish means sets bar. Lab measurements leaves the key off.

mark.error point
{
  "mark": { "error": "point" }
}
mark.error bar
{
  "mark": { "error": "bar" }
}

Choosing Point again deletes the key when the example omitted it, and writes point when the example set it. Salt, Monday to Friday keeps pointSize either way. Choosing Bar writes bar and leaves the other mark keys in place.

Tooltip

tooltip is on for an error bar when the key is omitted. Hovering a category shows the span from low to high. tooltip: false turns the card off. tooltip: true turns it on.

tooltip false
{
  "tooltip": false
}
tooltip true
{
  "tooltip": true
}

tooltip.fields chooses the rows, and tooltip.position places the card. Change those in the playground. Turning the card off and on again puts that object back. An omitted tooltip comes back as an omitted key.

An error bar draws one series, and this renderer does not paint a legend. legend is not a control here.

The rest of the spec

mark.pointSize is the point radius in pixels. The default is 4.5. Salt, Monday to Friday sets 5, and the whisker caps grow with that radius. encoding.y.scale.domain holds the axis when the means sit in a narrow band. A rule annotation can mark a reference, the way Dish means marks the blank. Theme presets and the full option list live on the playground.