Plotly · Class

go.Candlestick

A Plotly graph-object trace for displaying financial open, high, low, and close values at each x coordinate. It is commonly used with time-based x values and supports configurable candle appearance and interaction.

How it works

Construct a financial trace by supplying one x coordinate and corresponding open, high, low, and close values for each candle. Optional trace properties control appearance, hover behavior, axes, visibility, and related chart behavior.

Syntax

plotly.graph_objects.Candlestick(*arg=None*, *close=None*, *customdata=None*, *decreasing=None*, *high=None*, *hoverinfo=None*, *hoverlabel=None*, *hovertemplate=None*, *hovertemplatefallback=None*, *hovertext=None*, *ids=None*, *increasing=None*, *legend=None*, *low=None*, *name=None*, *opacity=None*, *open=None*, *selectedpoints=None*, *showlegend=None*, *text=None*, *uid=None*, *uirevision=None*, *visible=None*, *whiskerwidth=None*, *x=None*, *xaxis=None*, *xcalendar=None*, *xhoverformat=None*, *xperiod=None*, *xperiod0=None*, *xperiodalignment=None*, *yaxis=None*, *yhoverformat=None*, *zorder=None*, **kwargs*)

Parameters

Name	Type	Description
`arg`	`dict or Candlestick`	Optional property dictionary or object used to initialize the trace.
`close`	`array-like`	Closing values for the candles.
`customdata`	`array-like`	Additional data attached to points for hover or callbacks.
`decreasing`	`object`	Configuration for decreasing candles.
`high`	`array-like`	High values for the candles.
`hoverinfo`	`string or array-like`	Hover information configuration.
`hoverlabel`	`object`	Hover label styling configuration.
`hovertemplate`	`string or array-like`	Hover text template.
`open`	`array-like`	Opening values for the candles.
`increasing`	`object`	Configuration for increasing candles.
`low`	`array-like`	Low values for the candles.
`x`	`array-like`	Coordinates associated with the candles.

Returns

A plotly.graph_objects.Candlestick trace object.

Key points

Instantiate the trace with go.Candlestick, then place it in a Figure or another graph-object composition.
Use x to associate every OHLC observation with a coordinate, typically a date or time.
The rectangular candle body communicates the difference between opening and closing values.
The candle's vertical line communicates the complete low-to-high span.
A candle is increasing when close exceeds open and decreasing when close is lower than open.
Use the candlestick trace reference when you need to discover or configure attributes beyond the constructor's common inputs.

Common mistakes

Each candle requires values representing open, high, low, and close; omitting one of these core price series prevents the intended OHLC representation.
Color direction is automatic by default, so explicitly configure increasing or decreasing styling when the default colors are unsuitable.

Example: Basic candlestick chart

import plotly.graph_objects as go

fig = go.Figure(go.Candlestick(
    x=["2024-01-01", "2024-01-02"],
    open=[100, 103],
    high=[105, 106],
    low=[98, 101],
    close=[103, 102],
))
fig.update_layout(xaxis_rangeslider_visible=False)
fig.show()

Creates a two-period financial chart from open, high, low, and close values, then hides the default range slider.

When to use it

Price-history visualization

Plot historical market data with one OHLC observation per trading interval.

Trend and volatility analysis

Show directional movement through candle bodies and high-low wicks.

Interactive financial dashboards

Embed a finance trace in a larger graph-object figure with customized hover and axis behavior.

Interview questions

QWhat data does a Candlestick trace represent?

Candlestick is a graph-object finance trace for visualizing open, high, low, and close values at each x coordinate. The x values are most commonly timestamps.

Follow-up: How would you disable the built-in navigation control? Set the figure layout's x-axis property xaxis_rangeslider_visible to False.

QWhich constructor inputs are central to building the trace?

The constructor accepts trace properties such as x, open, high, low, close, increasing, decreasing, hovertemplate, and axis assignments. The complete signature also accepts an optional arg object and additional keyword properties.

Follow-up: How can candle colors be customized? Configure the increasing and decreasing styling objects or their relevant color properties.

QHow should the visual components of a candle be interpreted?

A candle's body shows the spread between open and close, while its line spans the low-to-high range. Candles are classified as increasing or decreasing according to the close relative to the open.

Follow-up: What is a practical reason to use x values based on time? Financial OHLC observations are naturally indexed by trading time, which makes trends and intervals readable.

plotly.graph_objects.Ohlc
plotly.graph_objects.Figure
plotly.graph_objects.Layout

Source: plotly.graph_objects.Candlestick — 7.1.0 documentation. Checked 2026-10-15.