Plotly · Function

px.icicle

Creates an interactive icicle chart for hierarchical data, using rectangular sectors arranged from root to leaves. The hierarchy can be supplied explicitly with names and parents or inferred from a path of columns.

How it works

Pass hierarchical data to px.icicle using either names and parents or a path of dataframe columns. The function converts the input into a Plotly Figure whose rectangular sectors represent the hierarchy, optionally sized, colored, labeled, and constrained with chart options such as branchvalues and maxdepth.

Syntax

plotly.express.icicle(data_frame=None, names=None, values=None, parents=None, path=None, ids=None, color=None, color_continuous_scale=None, range_color=None, color_continuous_midpoint=None, color_discrete_sequence=None, color_discrete_map=None, hover_name=None, hover_data=None, custom_data=None, labels=None, title=None, subtitle=None, template=None, width=None, height=None, branchvalues=None, maxdepth=None)

Parameters

Name	Type	Description
`data_frame`	`DataFrame or array-like or dict`	DataFrame, array-like, or dict used as the input data; optional when other arguments provide the data.
`names`	`str, Series, or array-like`	Column name or array-like values used as sector labels.
`values`	`str, Series, or array-like`	Column name or array-like values defining sector quantities.
`parents`	`str, Series, or array-like`	Column name or array-like values identifying each sector's parent.
`path`	`list of str, Series, or array-like`	Ordered hierarchy columns used to construct the tree.
`ids`	`str, Series, or array-like`	Column name or array-like values providing sector identifiers.
`color`	`str, Series, or array-like`	Column name or array-like values used for coloring sectors.
`branchvalues`	`str`	Controls whether sector values are interpreted as branch totals or leaf totals.
`maxdepth`	`int`	Limits the number of hierarchy levels shown.

Returns

plotly.graph_objects.Figure

Key points

The chart encodes hierarchical relationships as rectangular sectors arranged from the root toward leaf nodes.
Each input item becomes a sector in the generated icicle figure.
Use path to derive multiple hierarchy levels from an ordered list of dataframe columns.
The values argument controls the numeric quantity associated with each sector.

Common mistakes

Do not combine path with ids or parents; supply either the explicit hierarchy fields or the path form.
Use None for missing hierarchy values when the input table is not rectangular.
Represent the hierarchy root with an empty parent string when using explicit parents.

Example: Create an icicle chart

import plotly.express as px

data = {
    "character": ["Eve", "Cain", "Seth", "Enos"],
    "parent": ["", "Eve", "Eve", "Seth"],
    "value": [10, 14, 12, 10],
}
fig = px.icicle(
    data,
    names="character",
    parents="parent",
    values="value",
)
fig.show()

Builds an icicle chart from explicit labels, parent relationships, and sector values.

When to use it

Inspect hierarchical relationships

Exploring nested categories, organizational structures, or other parent-child data.

Size sectors by values

Comparing quantitative measures across tree nodes.

Use column paths

Building a hierarchy from levels already stored as dataframe columns.

Limit displayed depth

Showing only an upper portion of a deep hierarchy.

Interview questions

QWhat kind of visualization does px.icicle produce, and how is its hierarchy specified?

px.icicle creates a rectangular-sector visualization for hierarchical data, cascading from a root toward leaves in one direction. The hierarchy can be described with names and parents, or with a path of dataframe columns.

Follow-up: How would you represent an irregular hierarchy in a path-based dataframe? Supply None for missing values so the non-rectangular data is represented explicitly.

QHow does px.icicle interpret its data input and column arguments?

The first argument is data_frame. When it is a dataframe, arguments such as names, parents, and values can be column-name strings; array-like and dictionary inputs are transformed internally into a dataframe.

Follow-up: What dependency may be needed by Plotly Express? NumPy is required by Plotly Express, and pandas is additionally needed for trendlines.

QWhen should path be used instead of names and parents?

Use path when hierarchy levels correspond to a sequence of dataframe columns. In that mode, do not provide ids or parents, because path already defines the hierarchy.

Follow-up: How can you control the visible depth of the result? Use maxdepth to limit how many hierarchy levels are displayed.

plotly.express.sunburst
plotly.express.treemap
plotly.graph_objects.Icicle

Source: plotly.express.icicle — 6.3.0 documentation. Checked 2026-10-15.