Bar list

A bar list is ranked rows with no axes. The label sits on the row, a track shows the value against the largest row, and the formatted value sits on the right. It is a list, not a chart you read off a scale.

When to use it

Use a bar list for a top-n list: pages, payment methods, services. The reader wants the name and the number, in the order you pass. Top pages is five rows. Payments by method is twelve. Top services is four.

A bar compares categories on a scale. A horizontal bar still has an axis, from zero to the top of the range. A bar list has no axis. The number is printed. The track is a share of the largest row, not a scale you measure.

Order is the order of the rows. mark.sort does not apply to a bar list. Setting it warns CK3010. Sort the data before you pass it. A long comparison that needs a grid is a bar.

Where it loads

Bar list is not in the line bundle or in @chartkitdev/core/all. render() from all returns an error SVG for this type. Call renderBarList from the chart entry.

import
import { renderBarList } from "@chartkitdev/core/charts/bar-list";

Data

Each row is a label and a number. encoding.x is the label. encoding.y is the value. Top pages uses page and visits. Payments by method uses method and amount. Top services uses name and value.

encoding.y can be a field name. The smallest spec does that. An object adds a format. Top pages uses the compact preset, so 1,840 prints as 1.8K. Payments by method adds a dollar prefix. Top services adds a suffix. The format is how the number on the right is written. It is not a separate control, because each example names a different field.

encoding.y.format
{
  "encoding": {
    "y": { "field": "visits", "format": "compact" }
  }
}

A row with a missing label or a missing number is skipped. There is one series. A second number is a second list, or a bar.

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 list. version, type, data, encoding, and a11y.alt are required. mark can be omitted. The track is the short bar. There are no axes and no legend. Omit size.height and the chart grows with the rows, 28px each. A height in the spec wins and can clip rows that do not fit. Payments by method sets 640 by 360, which fits its twelve rows. The docs preview supplies a width when the spec does not.

spec.json
{
  "version": "1",
  "type": "bar-list",
  "data": [
    {
      "page": "/pricing",
      "visits": 1840
    },
    {
      "page": "/docs",
      "visits": 1420
    },
    {
      "page": "/gallery",
      "visits": 980
    }
  ],
  "encoding": {
    "x": "page",
    "y": "visits"
  },
  "a11y": {
    "alt": "Pricing leads the page list."
  }
}

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/bar-listBundle@chartkitdev/core/charts/bar-listFamilyLibrary
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 three lists. Top pages is the short bar, with visits in the tooltip. Payments by method is the full-row wash. Top services turns the tooltip off, because the rate is already on the row.

Track

mark.track is the shape of the row. Omit it, or set bar, and each row is a short rounded bar on a faint track. The label sits on the bar. The value sits at the right. That is Top pages and Top services.

row is a full-height wash behind the label. The width is still the value against the largest row. The count stays on the right. Payments by method uses row. The type is still bar-list. A horizontal bar chart is type: "bar" with mark.orientation set to horizontal.

mark.track
{
  "mark": { "track": "row" }
}

Choosing Bar on an example that omitted mark.track removes the key, so the default stays the short bar. Choosing Bar on Payments by method writes bar, because that example had set row.

Tooltip

The label and the value are already on the row, so a bar list is readable with no hover card. tooltip is still the shared hover key. It is on when the key is omitted. tooltip: false turns the card off. tooltip: true turns it on. Top services sets false.

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

tooltip.fields chooses the rows in the card. Top pages names the page and the visits. Change those fields in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed.

The rest of the spec

encoding.y.format is the number on the right. A preset such as compact, or an object with a prefix, suffix, or decimals, is the whole formatting story. There is no legend and no axis. Theme presets live on the playground, with the full option list.