Bar

A bar compares a measure across categories. Each category is one bar. A second measure, or a series field, is another bar in that same category, grouped beside the first or stacked on it.

When to use it

Use a bar when the question is which category is larger. The categories do not have to be a sequence. A line is the chart for a trend, where the slope between points is the point. A combo is the chart when one series should stay a bar and another should be a line, often because the units differ. A pie or a donut is the chart for a few parts of one total.

A long list of names reads better as horizontal bars. Revenue by region is that chart. Do not use a bar for a ranked list of pages with a value on the right. That is a bar list, a different type.

One bar type

Grouped, stacked, and horizontal bars are all type: "bar". There is no separate stacked-bar type. mark.orientation turns the bars. mark.stack groups them, stacks them, or draws each category as a share of 100%.

A time series of parts that add into one shape is a stacked area. Bars plus a line in the same spec are a combo.

Data

Each row is one category and one or more numbers. encoding.x is the category. encoding.y is a field name, or a list of channels when each series is its own column.

Signups by month is one series, signups, across five months. Revenue by region is one series, revenue, across four regions. Traffic by channel is three columns, search, direct, and social, listed on encoding.y.

Long form uses one value column and a series column. Easy, steady, and hard has a row per week and band. encoding.y is minutes. encoding.series is band.

encoding.series
{
  "encoding": { "x": "week", "y": "minutes", "series": "band" }
}

a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.

A spec that renders

This is the smallest bar. version, type, and a11y.alt are required. Orientation, stacking, and labels come from the bar defaults, so mark can be omitted. The bars are vertical. One series is not stacked. Labels are off.

spec.json
{
  "version": "1",
  "type": "bar",
  "data": [
    {
      "month": "Jan",
      "signups": 100
    },
    {
      "month": "Feb",
      "signups": 180
    },
    {
      "month": "Mar",
      "signups": 150
    }
  ],
  "encoding": {
    "x": "month",
    "y": "signups"
  },
  "a11y": {
    "alt": "Signups peaked in February at 180, after 100 in January."
  }
}

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/barBundle@chartkitdev/core/allFamilyCore
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 bar specs. Signups by month is one series. Revenue by region is horizontal. Traffic by channel stacks three columns. Easy, steady, and hard stacks a series field, and the tooltip is an index card.

Orientation

mark.orientation is vertical or horizontal. Omit it and the bars stand up. horizontal runs the categories down the side and the numbers along the bottom. That is the right direction when the names are long.

mark.orientation
{
  "mark": { "orientation": "horizontal" }
}

Stack

mark.stack is how several series share a category. Omit it, or set none, and the bars sit side by side. That is grouped. stack puts the series in one bar. percent makes each category 100%, so you compare the mix rather than the total.

mark.stack
{
  "mark": { "stack": "stack" }
}
mark.stack percent
{
  "mark": { "stack": "percent" }
}

One series looks the same grouped or stacked. The key still writes. Traffic by channel and Easy, steady, and hard are the specs where the choice changes the picture.

Labels

mark.labels draws the value on each bar. Omit it, or set false, and the bars are unlabeled. Set true and the number is drawn. A vertical bar puts it above the bar. A horizontal bar puts it at the end.

mark.labels
{
  "mark": { "labels": true }
}

mark.labelPosition and mark.labelFormat place and format that number. Setting either one turns labels on. Change those in the playground. Turning labels off and on again puts the example's position and format back.

Legend

A bar with one series hides the legend. A bar with several series shows it. Omit legend, or set true, and the legend sits on top. false hides it. legend.position is top, right, bottom, left, or inside.

legend.position
{
  "legend": { "position": "top" }
}

Tooltip

tooltip is on for a bar when the key is omitted. Hovering a bar shows the category and the value. tooltip: false turns the card off. tooltip: true turns it on.

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

tooltip.fields chooses the rows in the card, and tooltip.position places it. Easy, steady, and hard sets an index card with a crosshair. Change those in the playground. Turning the card off and on again puts that object back.

The rest of the spec

mark.cornerRadius rounds the corners. mark.gap is the space between bars, as a fraction of the band. mark.stackTotal labels the total of a stack. axes.x.title and axes.y.title name the axes. Theme presets live on the playground, with the full option list.