Histogram
A histogram counts one quantitative field into equal-width bins. Each bar is a range of values. The height is how many rows fall in that range. encoding.x is the value to bin.
When to use it
Use a histogram when the question is how a single number is spread: where the counts pile up, and how long the tail is. Checkout time is two hundred durations. Response time distribution is the same idea in milliseconds.
A bar compares categories you already named. The categories are the data. A histogram invents the ranges by splitting one numeric field. A density draws a smooth kernel of the same sample. It answers where the mass sits. A histogram answers with counts in bins.
Data
Each row is one observation. encoding.x is a quantitative field. A string field name is enough. Checkout time bins ms. Checkout scores bins score.
There is one series. A histogram does not take a color field, and the renderer draws no legend. legend: false on Response time distribution changes nothing you can see.
encoding.y is a count you already computed. The bars then use those counts, and mark.bins is ignored because the bins are the rows. How the weights fall, in the orchard showcase, is that chart. Set it in the playground when the sample is already counted.
{
"encoding": { "x": "grams", "y": "crates" }
}a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest histogram. version, type, and a11y.alt are required. Four times, and no mark. The bin count defaults to 8. The bin rule defaults to count, which uses that number.
{
"version": "1",
"type": "histogram",
"data": [
{
"ms": 12
},
{
"ms": 18
},
{
"ms": 18
},
{
"ms": 40
}
],
"encoding": {
"x": "ms"
},
"a11y": {
"alt": "Most times sit low, with one slower value at 40 milliseconds."
}
}Install core and the adapter for your framework. The menu in the sidebar picks the snippet. spec is the JSON above.
npm install @chartkitdev/core
npm install @chartkitdev/react
import { Chart } from "@chartkitdev/react";
export function Panel() {
return <Chart spec={spec} />;
}npm install @chartkitdev/core
npm install @chartkitdev/vanilla
import { mount } from "@chartkitdev/vanilla";
const chart = mount(document.querySelector("#chart"), spec);
chart.update(spec);npm install @chartkitdev/core
npm install @chartkitdev/vue
<script setup>
import { Chart } from "@chartkitdev/vue";
</script>
<template>
<Chart :spec="spec" />
</template>npm install @chartkitdev/core
npm install @chartkitdev/svelte
<script>
import { Chart } from "@chartkitdev/svelte";
</script>
<Chart {spec} />npm install @chartkitdev/core
npm install @chartkitdev/astro
---
import { Chart } from "@chartkitdev/astro";
---
<Chart spec={spec} />npm install @chartkitdev/core
npm install @chartkitdev/solid
import { Chart } from "@chartkitdev/solid";
export function Panel() {
return <Chart spec={spec} />;
}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} />;
});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;
}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 histogram specs. Checkout time is two hundred times in sixteen bins. Checkout scores is four scores in two bins. Response time distribution is the homepage sample in fourteen bins.
Bins
mark.bins is the number of equal-width bins when the rule is count or omitted. Omit it and the chart uses 8. Checkout time sets 16. Checkout scores sets 2. Response time distribution sets 14. The renderer keeps the count between 1 and 60.
{
"mark": { "bins": 16 }
}The slider writes mark.bins. Sturges, square root, and Freedman–Diaconis ignore that number and choose a count from the data. Switch the rule back to count and the number is used again.
Bin rule
mark.bin chooses how the edges are picked. Omit it, or set count, and mark.bins is the count. sturges uses the log of the sample size. sqrt uses the square root of the sample size. fd is Freedman–Diaconis: the bin width comes from the interquartile range.
{
"mark": { "bin": "sturges" }
}width uses mark.binWidth, a width in data units. That pair lives in the playground. These three examples all use the count rule.
Tooltip
tooltip is on for a histogram when the key is omitted. Hovering a bar shows the range and the count. tooltip: false turns the card off. tooltip: true turns it on.
{
"tooltip": false
}{
"tooltip": true
}tooltip.fields chooses the rows in the card. These examples omit the key, so the card uses the bin label and the count. Turning the card off and on again puts that object back when the example had one, and deletes the key when the example omitted it.
The rest of the spec
mark.binLabel draws the bin count at the top right of the plot. Omit it and that corner stays empty. mark.binWidth is the width when mark.bin is width. A pre-binned encoding.y is a different data shape. Theme presets live on the playground, with the full option list.