Candlestick

A candlestick chart shows how a price moved in each trading session. Each candle has a body from the open to the close and a wick from the low to the high, coloured by whether the session rose or fell.

The candlestick ships as its own package, @graphysdk/geom-candlestick, on a 0.x version line. While it is on 0.x, a minor release may change its aesthetics, style parts or look; pin a caret range (^0.1.0) to take only patches. Tell us what works and what doesn’t on Discord.

Install

npm install @graphysdk/geom-candlestick

It peer-depends on @graphysdk/react and nothing else. Register the plugin once with createGraphyKit, which adds kit.geom.candlestick() and binds kit.GraphProvider to the same plugin:

import {
  createGraphyKit,
  GraphRenderer,
  highlight,
  styles,
} from '@graphysdk/react';
import { candlestick } from '@graphysdk/geom-candlestick';

const kit = createGraphyKit({ plugins: [candlestick] });

One candle per session

Map the session to x, and each price to its aesthetic:

const data = {
  columns: [
    { key: 'date', label: 'Date' },
    { key: 'open', label: 'Open' },
    { key: 'high', label: 'High' },
    { key: 'low', label: 'Low' },
    { key: 'close', label: 'Close' },
  ],
  rows: [
    { date: 'Apr 01', open: 100, high: 103, low: 99, close: 102 },
    { date: 'Apr 02', open: 102, high: 104, low: 101, close: 101 },
    // …
  ],
};

const spec = kit.pipe(
  kit.createSpec({ x: 'date' }),
  kit.geom.candlestick({
    aes: { open: 'open', high: 'high', low: 'low', close: 'close' },
  }),
  kit.scale.x.discrete(),
  kit.scale.y.continuous()
);

export function Prices() {
  return (
    <kit.GraphProvider spec={spec} data={data}>
      <GraphRenderer />
    </kit.GraphProvider>
  );
}

All four prices are required. The sessions sit one per band at equal spacing, so a weekend or holiday takes no room. The session axis is always discrete, even for dates. The price axis fits the prices rather than holding zero: A session rises when its close is at or above its open, so a doji (open equal to close) counts as rising and draws as a flat body. The close is the candle’s y: a highlight or a headline that reads y reads the close. A y in the root mapping does not reach the candlestick layer, and the compiler warns that it is ignored.

Horizontal

Add kit.coord.flip(). The sessions move to the vertical axis and the wicks lie across.

Body width

width sets how much of its band each body spans, as a fraction from just above 0 up to 1, like a bar’s. It defaults to 0.6; at 1 neighbouring bodies touch. The wick stays on the band centre.

kit.geom.candlestick({
  aes: { open: 'open', high: 'high', low: 'low', close: 'close' },
  params: { width: 0.8 },
});

A width above 1 is clamped to the full band, and one at or below 0 falls back to the default; the compiler warns in both cases.

Styling

A candle’s colour says which way its session went, so it comes from a part per direction. The bodies’ other properties and the wicks have builders of their own:

Builder	Properties	Default
`kit.style.geom.candlestick.rising()`	`fill`, `stroke`	The positive trend colour
`kit.style.geom.candlestick.falling()`	`fill`, `stroke`	The negative trend colour
`kit.style.geom.candlestick()`	`alpha`, `fillAlpha`, `strokeWidth`	1px border
`kit.style.geom.candlestick.wick()`	`stroke`, `alpha`, `strokeWidth`, `dashArray`	1px, in its direction’s `stroke`

const spec = kit.pipe(
  // …
  styles({
    defaults: [
      kit.style.geom.candlestick.rising({
        fill: 'transparent',
        stroke: '#1f7a6d',
      }),
      kit.style.geom.candlestick.falling({
        fill: '#3a3833',
        stroke: '#3a3833',
      }),
      kit.style.geom.candlestick.wick({ stroke: '#898373' }),
    ],
  })
);

A wick takes its direction’s stroke unless a wick entry names one. A chart-wide style.geom({ fill }) does not reach the candles, so it cannot flatten them to one colour. To colour the candles from the data instead, see Mapped colour. Each session carries a candlestickDirection variable, 'rising' or 'falling', which replaces a data column of the same name. Name it in an entry’s where to style one direction’s bodies or wicks:

kit.style.geom.candlestick(
  { strokeWidth: 2 },
  { where: { variable: 'candlestickDirection', eq: 'falling' } }
);

Mapped colour

color is opt-in. Map it to candlestickDirection to colour the directions through a colour scale, with a legend:

const spec = kit.pipe(
  kit.createSpec({ x: 'date' }),
  kit.geom.candlestick({
    aes: {
      open: 'open',
      high: 'high',
      low: 'low',
      close: 'close',
      color: 'candlestickDirection',
    },
  }),
  kit.scale.x.discrete(),
  kit.scale.y.continuous(),
  kit.scale.color.discrete({
    domain: ['rising', 'falling'],
    range: ['#1f8a70', '#c8453b'],
  })
);

Map it to a column you compute to colour by your own rule. A third value paints a doji (open equal to close) apart from both directions:

const rows = sessions.map((row) => ({
  ...row,
  move: row.close > row.open ? 'up' : row.close < row.open ? 'down' : 'flat',
}));

kit.scale.color.discrete({
  domain: ['up', 'down', 'flat'],
  range: ['#1f8a70', '#c8453b', '#8a8a8a'],
});

Hollow candles colour each session by its close against the previous close, and hollow out the bodies that closed above their open:

const rows = sessions.map((row, index) => ({
  ...row,
  versusPrevious:
    row.close >= (sessions[index - 1]?.close ?? row.open) ? 'higher' : 'lower',
}));

// aes: { …, color: 'versusPrevious' }
styles({
  overrides: [kit.style.geom.candlestick.rising({ fill: 'transparent' })],
});

Or map it to a data column to colour the candles by its groups. Colour then no longer shows the direction, so give it a second cue, such as hollow rising bodies:

styles({
  overrides: [kit.style.geom.candlestick.rising({ fill: 'transparent' })],
});

A mapped colour replaces the direction parts’ built-in colours and beats their defaults entries. An overrides entry beats the mapped colour, which is why the hollow bodies above are an override. A wick follows its body’s colour unless a wick entry names one.

Hover and highlight

Hovering a session emphasises its candle, and the tooltip lists its open, high, low and close, each labelled by its column’s label (or its key when it has none). A press anywhere along the wick takes its session. A highlight raises each matched candle whole, wick and body together. Match on a price, or on the direction:

const spec = kit.pipe(
  // …
  highlight({ variable: 'candlestickDirection', eq: 'falling' })
);

Not yet supported

The editor’s chart-type picker and the chart agent. In editable mode the candlestick renders, hovers, selects and takes annotations on each session’s close, but it is authored in code.
Data labels. dataLabels prints nothing on a candle yet.
Volume and OHLC bars. Draw volume as a separate bar chart; OHLC ticks in place of a body are not drawn yet.
Aggregation. Duplicate rows for one session all draw; aggregate them first with transform.aggregate().

Get Started

Core concepts

Chart types

Annotations & emphasis

Rendering

Configuration

Advanced

Extending

Install

One candle per session

Horizontal

Body width

Styling

Mapped colour

Hover and highlight

Not yet supported

​Install

​One candle per session

​Horizontal

​Body width

​Styling

​Mapped colour

​Hover and highlight

​Not yet supported

Install

One candle per session

Horizontal

Body width

Styling

Mapped colour

Hover and highlight

Not yet supported