Candlestick
A candlestick is one session. The body runs from open to close. The wick runs from low to high. A close at or above the open uses the positive color. A lower close uses the negative color.
When to use it
Use a candlestick when each mark is a session, not a single number. Northstar is ten days. The body shows whether the day finished up or down, and the wick shows the high and the low. A volume pane sits under the price. CK / USD is twelve sessions on day names, with no volume. A week of prices is five dated sessions. Wednesday is the only day that closed down.
A line through the closes hides the range and the direction of the session. A bar of the close, or of the volume, is one length. It does not show open against close.
A range bar is a floating bar from a low to a high. It does not split open from close, and it has no wick. An error bar is a whisker around a point or a bar: a measurement and a spread, not a session.
Candlestick, range bar, and error bar
type: "candlestick" requires encoding.x, open, high, low, and close. The body is open to close. The wick is low to high. Up and down come from the theme tokens positive and negative.
type: "bar-range" uses encoding.low and encoding.high. The bar does not start at zero, and it has no open or close. columnrange and floating-bar repair to bar-range.
type: "errorbar" draws whiskers from low and high, or from encoding.error as a margin around y. mark.error is point or bar. That is a summary of a sample, not a price.
Data
Each row is one session. Northstar uses date, open, high, low, close, and volume. A week of prices uses day and the four prices. CK / USD uses d for the day name. The field names are yours. The channels are open, high, low, and close.
The high has to be at least the larger of open and close. The low has to be at most the smaller. Otherwise validate reports CK3003. A temporal x is formatted from the span, so Northstar reads as dates. A category x uses the labels you pass. CK / USD does that.
encoding.volume is optional. When it is set, bars of the same up and down colors sit under the price, at a lower opacity. Omit it and the pane is gone. CK / USD and A week of prices omit it.
a11y.alt is required. One sentence, 10 to 500 characters, with the point of the chart.
A spec that renders
This is the smallest candlestick. version, type, and a11y.alt are required. One session, no volume, so mark can be omitted. The body gap defaults to 0.3 of the band. Wheel zoom defaults to x for this type.
{
"version": "1",
"type": "candlestick",
"data": [
{
"day": "Mon",
"open": 5,
"high": 7,
"low": 4,
"close": 6
}
],
"encoding": {
"x": "day",
"open": "open",
"high": "high",
"low": "low",
"close": "close"
},
"a11y": {
"alt": "Monday opened at 5 and closed at 6, with a high of 7."
}
}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;Candlestick ships in @chartkitdev/core/all. createRenderer([candlestick]) from @chartkitdev/core/charts/candlestick is the one-chart build. The type string is candlestick.
Each option below is a key on the spec. The demo changes that key and updates the chart and the snippet together.
Examples
Northstar is the gallery candle: ten sessions, a date axis, and volume. CK / USD is the homepage candle: twelve day names, no volume. A week of prices is the short dated week, with Wednesday as the down day.
Volume
encoding.volume names the volume field. Set it and a pane opens under the price, about a fifth of the plot. The bars use the session's up or down color. Omit the key, or remove it, and the chart is price only.
{
"encoding": { "volume": "volume" }
}Northstar sets volume. Turning the pane off deletes that key and leaves open, high, low, and close in place. Turning it on puts the example's volume channel back. CK / USD and A week of prices have no volume field, so On has nothing to restore and the control stays off.
Tooltip
tooltip is on for a candlestick when the key is omitted. Hovering a session shows open, high, low, and close. tooltip: false turns the card off. tooltip: true turns it on.
{
"tooltip": false
}{
"tooltip": true
}tooltip.fields chooses the rows in the card, and tooltip.position places it. Change those in the playground. Turning the card off and on again puts that object back. An example that omitted tooltip gets the key removed, so the default stays on.
The rest of the spec
mark.gap is the space around the body, as a fraction of the band. The default is 0.3. interaction.zoom defaults to x for a candlestick and to none for other types. Up and down colors are theme.tokens.positive and theme.tokens.negative, not a series palette. The candles do not draw a series legend. Theme presets live on the playground, with the full option list.