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": [
{ "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.
{
"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.
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 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": 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": 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": 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.