Range area

A range area draws a band between a low and a high across an ordered x. encoding.y is an optional center line through that band. The type is area-range.

When to use it

Use a range area when the question is an interval around a measure: a forecast that opens after today, a confidence band, or a low and a high that travel with a line. Revenue forecast is that chart. The line is known from January, and the band starts in April. Seats filled at Pell Hall nests an 80% band inside a 95% band and dashes the line once the forecast starts.

Use a line when you only have the measure. Use a stacked area when several series add into one total. Use a range bar when each category is a span and there is no center line.

Range area, filled line, and stacked area

A filled line is type: "line" with mark.area set to true. There is no type: "area". Area is the note for that fill. The fill runs from the line down to the baseline. It is one series painted to zero, and a second series can overlap it.

A stacked area adds the series. The top of the shape is the total, or 100% when mark.stack is percent. The bands are parts. They sit on each other.

A range area band is the span from low to high. Nested bands share the center line and paint the wider interval underneath. They do not add. arearange repairs to area-range.

Data

Each row is one x, a low, a high, and an optional center. encoding.x is the category or the time. encoding.low and encoding.high name the band. encoding.y is the center line. Revenue forecast uses lo, hi, and revenue.

A null low or high breaks the band on that row. That is how a forecast starts later than the line. Columns named low, lo, or min, and high, hi, or max, are found when the keys are omitted. Name them anyway on a first chart.

Several bands are a y list. Each item has lo, hi, and a title. One more item, with field, is the center line. Seats filled at Pell Hall lists a 95% band, an 80% band, and seats. A title that is a percent, such as 95%, is labeled 95% interval when the center line is drawn. low and high on a y item repair to lo and hi.

encoding.y bands
{
  "encoding": {
    "y": [
      { "lo": "wideLo", "hi": "wideHi", "title": "95%" },
      { "lo": "tightLo", "hi": "tightHi", "title": "80%" },
      { "field": "seats", "title": "Seats" }
    ]
  }
}

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

A spec that renders

This is the smallest range area. version, type, and a11y.alt are required. Six months. The band is empty until April, so lo and hi are null on the earlier rows. The center line comes from encoding.y, so mark can be omitted.

spec.json
{
  "version": "1",
  "type": "area-range",
  "data": [
    {
      "month": "Jan",
      "revenue": 420,
      "lo": null,
      "hi": null
    },
    {
      "month": "Feb",
      "revenue": 390,
      "lo": null,
      "hi": null
    },
    {
      "month": "Mar",
      "revenue": 450,
      "lo": null,
      "hi": null
    },
    {
      "month": "Apr",
      "revenue": 510,
      "lo": 470,
      "hi": 560
    },
    {
      "month": "May",
      "revenue": 540,
      "lo": 480,
      "hi": 610
    },
    {
      "month": "Jun",
      "revenue": 580,
      "lo": 500,
      "hi": 670
    }
  ],
  "encoding": {
    "x": "month",
    "y": {
      "field": "revenue",
      "title": "Forecast"
    },
    "low": "lo",
    "high": "hi"
  },
  "a11y": {
    "alt": "Revenue is forecast from April, with a band that widens through June."
  }
}

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/area-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 area specs. Revenue forecast is the gallery and core chart: one band, a center line, and a rule at April. Seats filled at Pell Hall is the showcase: two bands, a dashed forecast, and a full-house shade.

Center line

mark.line draws the center line through encoding.y. Omit it, or set true, and the line is on when y is set. false draws the band only.

mark.line false
{
  "mark": { "line": false }
}
mark.line true
{
  "mark": { "line": true }
}

Revenue forecast and Seats filled at Pell Hall leave mark.line unset, so the line is on. Turning the line off and on again puts that omitted key back. A chart that had set true comes back with true.

When the line and at least one band are both drawn, their names sit in a row above the plot. A percent band is named as an interval. That row is part of the marks. legend does not move it, so this page has no legend control. Placement stays in the playground.

Forecast dash

mark.strokeDash dashes the center line where a band is present and keeps the earlier line solid. Both parts use the line color. Omit it, or set false, and the whole line stays solid. Seats filled at Pell Hall sets true, so January through August stay solid and September onward is dashed.

mark.strokeDash
{
  "mark": { "strokeDash": true }
}

If the band covers every row, the whole center line is dashed. Turning the dash off deletes the key when the example omitted it, and writes false when the example had set it.

Tooltip

tooltip is on for a range area when the key is omitted. Hovering a position shows the line and the band. 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.

The rest of the spec

mark.stroke outlines the band. It is off unless you set true, so a nested interval stays a fill in the line color. A y item can set its own color. A combo series with mark range and lo / hi paints this same band under the other series. That spec type is combo. Theme presets, sampling, and axis format live on the playground, with the full option list.