Range bar

A range bar draws a floating bar from a low value to a high value. The bar is the span. It does not start at zero. The type is bar-range.

When to use it

Use a range bar when each category is a span and the ends are the story. Monthly temperature runs from a low to a high, and January sits below zero. Pell glasshouse is the same reading across a season, with a line through the midpoint.

Use a bar when the number is an amount from a baseline. Use an error bar when you have a center value and the span is the uncertainty around it. Use a range area when the span is a band along an ordered line.

Range bar, bar, and error bar

A bar encodes one amount. The bar grows from zero, or from the baseline you set. Several series group or stack. mark.orientation turns it horizontal. Those keys belong to type: "bar".

A range bar has two ends and no amount from zero. January can run from −2 to 6. The rectangle sits between those values. columnrange and floating-bar repair to bar-range.

An error bar draws a center and a whisker. With mark.error set to bar, the bar still starts at zero and the whisker is the range. A range bar has no whisker and no center mark. The bar is the range.

Data

Each row is one category and two numbers. encoding.x is the category. encoding.low and encoding.high are the ends. encoding.y is not required. Monthly temperature names min and max. Pell glasshouse names low and high.

encoding.low and encoding.high
{
  "encoding": { "x": "month", "low": "min", "high": "max" }
}

Columns named low, lo, or min, and high, hi, or max, are found when the keys are omitted. Name them on a first chart. A y object with lo and hi is the other spelling. A missing end skips that bar. When every low sits above its high, repair swaps the two fields.

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

A spec that renders

This is the smallest range bar. version, type, and a11y.alt are required. Four months, from min to max. The axis suffix is °C. There is no mark, because the span is the encoding.

spec.json
{
  "version": "1",
  "type": "bar-range",
  "data": [
    {
      "month": "Jan",
      "min": -2,
      "max": 6
    },
    {
      "month": "Apr",
      "min": 6,
      "max": 17
    },
    {
      "month": "Jul",
      "min": 17,
      "max": 29
    },
    {
      "month": "Oct",
      "min": 7,
      "max": 18
    }
  ],
  "encoding": {
    "x": "month",
    "low": "min",
    "high": "max"
  },
  "axes": {
    "y": {
      "format": {
        "style": "number",
        "suffix": "°C"
      }
    }
  },
  "a11y": {
    "alt": "July is the warmest month, from 17 to 29."
  }
}

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-rangeBundle@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 range bar specs. Monthly temperature is the gallery chart, with the four months from the core example. The chart title on that spec is Temperature. Pell glasshouse is the showcase: eight months, explicit ticks, and a season line through the midpoint.

Tooltip

tooltip is on for a range bar when the key is omitted. Hovering a bar shows the category and the span, low through 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.

A range bar draws one series, and this renderer does not paint a legend. legend is not a control here. Gap, orientation, and value labels belong to bar.

The rest of the spec

axes.y.format adds a suffix such as °C. axes.y.ticks places the grid. Pell glasshouse sets both, and sets the high field's scale domain so March and July stay inside the frame. A trendline annotation fits the midpoint. Theme presets and the full option list live on the playground.