Candlestick

Demo & usage

More examples

When to use

• A price history where the open, high, low and close of each session all matter.
• Any period where the RANGE within a session is part of the story, not just the closing level.
• For a closing price alone, a Line Chart is read faster; for a live feed, use the Live Stock variant.

Async states

• loading
• empty
• error
• retry

Outputs

Wire it to your API

This component is headless about transport: it renders what you give it and reports what the user asks for. Nothing below requires @styloviz/data — drive it from whatever you already use.

• This component does not emit a query, so it renders what you give it. Fetch on your own trigger and bind `sessions`, `loading` and `error`.
• Set `filtered` when a search or filter is active. It is the difference between "you have no orders" and "no orders match this filter" — telling a customer with 4,000 orders the first one reads as a bug.
• Normalize failures with `toSvDataError()` from `@styloviz/core`. It derives `retryable` from the status, so a 404 does not get a "Try again" button that can only fail again.

Full walkthrough: Connecting to a backend.

Customization & theming

• Linear or logarithmic price axis, with the scale actually in force named under the plot — including when log was asked for and could not be given. Negative prices (spreads, futures) plot on the linear axis; log is positive-only and falls back to linear over any range that reaches zero or below (or a series whose prices are all equal), naming the reason.
• `splits` back-adjusts prior sessions for a split or reverse split, disclosed in the note, in each adjusted session's accessible name and tooltip, and in its table row.
• `minSlotWidth` (default 3 px): when one candle per session would be narrower, consecutive sessions are merged OHLC-style (first open, highest high, lowest low, last close, summed volume) — the bar a coarser timeframe draws — and the merge is disclosed; the table still lists every session. `0` draws hairlines instead.
• Optional volume pane beneath the price pane.
• Up and down colours, a currency prefix, and plot size.
• A session missing any of the four prices is dropped and counted rather than patched, because filling a missing close with the open invents a doji and filling it with the previous close invents a gap.

Best practices

• Don't: Do not pad weekends, holidays or halts. The axis is ORDINAL — one slot per session you supply — because those are real absences of trading rather than missing data. A padded session is a candle that never traded, and drawing a continuous time axis across the gap squeezes the sessions that did happen. The chart states that horizontal distance is not time.
• Do: Use the logarithmic scale for any history longer than a year or so. On a linear axis a move from 10 to 20 and one from 100 to 110 are the same height though the first doubled the money — so the early years flatten into a line while recent noise fills the frame.
• Do: Send a session exactly as the feed reported it, contradictions included. A high below the body is not a rounding error: drawn as sent, the wick lands inside the body and the candle looks ordinary while asserting the price closed above the highest price it reached. The chart widens the range, marks the session and counts it in the note — repairing it upstream hides that the feed is wrong.
• Do: Pass `splits` when the feed is NOT already split-adjusted. An unadjusted 4-for-1 split draws as a 75 % collapse nobody lost money on; with `{ at, ratio }` every earlier session's prices are divided by the ratio (volume multiplied by it) and the adjustment is disclosed under the chart. Leave it empty for an adjusted feed — adjusting twice is its own crash.
• Don't: Do not expect the chart to convert time zones. It has none, by the same policy as the Line Chart: session labels are printed verbatim and never parsed as dates, so they cannot shift with the viewer's offset. Format each label once, in the exchange's zone — a session belongs to the exchange's calendar day, not the reader's.
• Tip: The up and down colours are emphasis rather than the encoding. Direction is also in the body fill — hollow for a rise, solid for a fall — and written as a word in every accessible name and table row, so recolouring them for a brand costs the reader nothing.

Accessibility

• The series is ONE tab stop: Arrow keys step session by session (clamped, not wrapping — a time series has a first and a last), Home/End jump to the ends, Enter/Space select. Each candle is a `role="button"` named with its direction as a word, its percentage move and all four prices.
• Sessions are keyed by position, not label, so two sessions that share a label are both drawn, both listed, and never highlight together.
• Direction is encoded three times over: colour, body fill (hollow up, solid down, which is what paper charts used before colour was available), and the word itself. Colour alone reaches nobody using a screen reader, is unreliable with a colour-vision deficiency, and is gone in print.
• `sv-data-summary-table` carries every session's direction, all four prices, the percentage change and the volume — figures the body and wick geometry only ever approximates. It lists every session individually even when dense data is drawn as merged candles, and a Note column marks split-adjusted prices and widened ranges.
• The volume bars are not a second set of tab stops: each belongs to a session that is already focusable.