Marks in Python
A mark describes data geometry inside a chart. Factories such as line(),
scatter(), and histogram() return lightweight Mark objects; the chart
container resolves their data and compiles them into one figure.
Bind Arrays or Columns
Pass arrays directly for small, local examples:
For table-shaped data, pass column names and provide data= on the mark or once
on the chart:
A mark-level data source overrides the chart-level source. Column-name resolution works with pandas, NumPy-compatible mappings, and Arrow-backed tables described in Data and columns. XY validates missing columns and incompatible channel lengths when the chart is built.
Choose a Mark Family
The Chart Gallery explains expected data shapes and family-specific choices.
Layer Marks in Declaration Order
Families mix freely inside one neutral xy.chart(...); children draw in
declaration order, so the bars below come first and the trend line paints over
them:
Shared Mark Behavior
name=gives a rendered series its legend label.x_axis=andy_axis=bind a mark to primary or named axes.- Data-driven
colorandsizechannels are available where the mark supports them. Their domains and palettes remain mark configuration, not colorbar configuration. style=is compiled for WebGL, SVG, and native raster output. Supported CSS declarations depend on the mark kind and invalid declarations fail early.- Children draw in declaration order, so broad fills normally come before lines and points.
key=supplies stable row identity for keyed browser data transitions, and mark-levelanimation=cascades over the chart'sxy.animation()policy field by field —xy.animation(duration=90)on a mark changes only the duration — or disables that mark withanimation=False. See Animations and data transitions.
Canvas and WebGL marks are not DOM elements. CSS selectors and Tailwind classes
cannot paint their geometry; use style= or the mark's paint props. In
particular, class_name= is adapter-only trace metadata, not a mark-painting
hook in the shipped browser, Reflex, SVG, or native renderers. See
Customize Each Part
for the compiled CSS subset.
This example drives one scatter's color= and size= from a data column-like
array (with colormap= and size_range= as mark configuration) while a second
mark uses plain paint options — name=, color=, dash=, and opacity=:
Compose a Multi-Mark Figure
Everything above composes: an uncertainty band drawn with area(..., base=)
goes first, the line and points layer over it, and a scatter of conversion
rates binds to a named right-hand axis:
Representation Does Not Change the Mark
Large marks can be transported as decimated lines or density summaries. That changes the screen representation, not the declarative mark or the canonical Python columns. Exact row callbacks require a live notebook or framework transport; a standalone export can only inspect its resident representation.
See Large data and performance for the tiering contract and Marks and components reference for signatures and defaults.
API Reference
xy.line
A line series with automatic M4 decimation for large inputs.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Y values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Line color. |
width | float | Line width in pixels. |
opacity | float | Line opacity from zero to one. |
curve | str | Interpolation mode, such as ``linear`` or ``smooth``. |
dash | Union[str, Sequence[float], None] | Optional line dash pattern. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
key | Any | Stable row identities, or a column name resolved from ``data``. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.scatter
A scatter series with optional color, size, and density encodings.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Y values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
color | Union[str, ColorLike, ArrayLike, None] | Constant color, values, or a column name. |
size | Union[str, Scalar, ArrayLike, None] | Constant marker size, values, or a column name. |
name | Optional[str] | Series label used by legends and tooltips. |
colormap | channels.ColormapLike | Color ramp for continuous values — a built-in name, a CSS ``linear-gradient(...)``, or a sequence of CSS colors (optionally ``(position, color)`` pairs). |
color_domain | Optional[tuple[float, float]] | Explicit minimum and maximum for continuous colors. |
size_range | tuple[float, float] | Minimum and maximum rendered marker sizes. |
opacity | Any | Marker opacity from zero to one. |
zoom_size_factor | float | Marker-size multiplier reached on deep zoom. |
zoom_opacity | Optional[float] | Optional marker opacity reached on deep zoom. |
zoom_emphasis | float | Zoom factor at which responsive targets are reached. |
density | Optional[bool] | Whether to force or disable density aggregation. |
symbol | Any | Marker symbol name. |
stroke | Any | Optional marker outline color. |
stroke_width | Any | Marker outline width in pixels. |
_artist_alpha | Any | Internal Matplotlib alpha override, scalar or per marker. |
_marker_path | Optional[dict[str, Any]] | Internal authored marker-path payload for Matplotlib adapters. |
_marker_glyph | Optional[str] | Internal single-glyph marker payload for Matplotlib adapters. |
_legend_trace_size | bool | Whether a Matplotlib legend derives marker size from this trace. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
key | Any | Stable row identities, or a column name resolved from ``data``. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.area
A filled area series between ``y`` and ``base``.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Y values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
base | Union[str, Scalar, ArrayLike] | Baseline value, values, or a column name. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Area fill color. |
opacity | float | Fill opacity from zero to one. |
line_color | Optional[str] | Outline color. |
line_width | float | Outline width in pixels. |
line_opacity | float | Outline opacity from zero to one. |
stroke_perimeter | bool | Whether to stroke the complete area perimeter. |
fill | Union[str, dict[str, str], None] | CSS fill value or linear gradient. |
curve | str | Interpolation mode, such as ``linear`` or ``smooth``. |
dash | Union[str, Sequence[float], None] | Optional outline dash pattern. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
key | Any | Stable row identities, or a column name resolved from ``data``. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.bar
A bar series supporting grouped, stacked, and normalized modes.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | Category positions or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Bar values, series matrix, or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Any | Constant color, values, or a column name. |
colors | Optional[list[str]] | Colors assigned to multiple series. |
width | Union[Scalar, ArrayLike] | Scalar or per-bar widths in category units. |
base | Union[str, Scalar, ArrayLike] | Baseline value, values, or a column name. |
mode | str | ``grouped``, ``stacked``, or ``normalized`` layout. |
orientation | str | ``vertical`` or ``horizontal`` orientation. |
series | Optional[list[str]] | Optional names for matrix-valued series. |
opacity | Any | Bar opacity from zero to one. |
corner_radius | Any | Bar corner radius in pixels. |
wedge_gap | float | Gap between neighbouring polar wedges, in pixels — constant from the hole to the rim. Deliberately a length, not an angle: an angular pad's gap is ``r · dtheta`` wide and so tapers to nothing toward the centre. Ignored outside ``coords="polar"``. |
stroke | Any | Optional bar outline color. |
stroke_width | Any | Bar outline width in pixels. |
_artist_alpha | Any | Internal Matplotlib alpha override, scalar or per bar. |
fill | Union[str, dict[str, str], None] | CSS fill value or linear gradient. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
key | Any | Stable row identities, or a column name resolved from ``data``. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.column
Create a vertical column series using the shared bar renderer.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | Category positions or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Column values, series matrix, or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Union[str, Sequence[str], None] | Constant color, values, or a column name. |
colors | Optional[list[str]] | Colors assigned to multiple series. |
width | Union[Scalar, ArrayLike] | Scalar or per-column widths in category units. |
base | Union[str, Scalar, ArrayLike] | Baseline value, values, or a column name. |
mode | str | ``grouped``, ``stacked``, or ``normalized`` layout. |
orientation | str | Orientation forwarded to the bar renderer. |
series | Optional[list[str]] | Optional names for matrix-valued series. |
opacity | float | Column opacity from zero to one. |
corner_radius | Union[float, tuple[float, float]] | Column corner radius in pixels. |
wedge_gap | float | Gap between neighbouring polar wedges, in pixels — constant from the hole to the rim. Deliberately a length, not an angle: an angular pad's gap is ``r · dtheta`` wide and so tapers to nothing toward the centre. Ignored outside ``coords="polar"``. |
stroke | Optional[str] | Optional column outline color. |
stroke_width | float | Column outline width in pixels. |
fill | Union[str, dict[str, str], None] | CSS fill value or linear gradient. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
key | Any | Stable row identities, or a column name resolved from ``data``. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.histogram
A one-dimensional histogram.
Props
| Prop | Type | Description |
|---|---|---|
values | Union[str, ArrayLike, None] | Sample values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
bins | Union[int, str, ArrayLike] | Bin count, edges, or automatic binning strategy. |
range | Optional[tuple[float, float]] | Explicit minimum and maximum input values. |
density | bool | Whether to normalize bin areas to one. |
cumulative | bool | Whether bins contain cumulative counts. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Any | Bar color. |
opacity | Any | Bar opacity from zero to one. |
corner_radius | Any | Bar corner radius in pixels. |
stroke | Any | Optional bar outline color. |
stroke_width | Any | Bar outline width in pixels. |
_artist_alpha | Any | Internal Matplotlib alpha override, scalar or per bin. |
fill | Union[str, dict[str, str], None] | CSS fill value or linear gradient. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.box
Grouped Tukey box plots from 1-D or column-oriented 2-D values.
Props
| Prop | Type | Description |
|---|---|---|
values | Union[str, ArrayLike, None] | Sample values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
x | Union[str, ArrayLike, None] | Optional group positions or a column name. |
group | Union[str, ArrayLike, None] | Optional grouping values or a column name. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Box color. |
width | float | Box width in category units. |
opacity | float | Box opacity from zero to one. |
orientation | str | ``vertical`` or ``horizontal`` orientation. |
show_outliers | bool | Whether to render outlier points. |
outlier_size | float | Outlier marker size in pixels. |
style | Optional[dict[str, StyleValue]] | Box-body fill, border, and overall opacity overrides. |
whisker_style | Optional[dict[str, StyleValue]] | Whisker stroke overrides. |
median_style | Optional[dict[str, StyleValue]] | Median-line stroke overrides. |
outlier_style | Optional[dict[str, StyleValue]] | Outlier marker fill, border, shape, and opacity overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.violin
Grouped bounded-resolution violin distributions.
Props
| Prop | Type | Description |
|---|---|---|
values | Union[str, ArrayLike, None] | Sample values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
x | Union[str, ArrayLike, None] | Optional group positions or a column name. |
group | Union[str, ArrayLike, None] | Optional grouping values or a column name. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Violin color. |
width | float | Violin width in category units. |
bins | int | Density resolution. |
opacity | float | Violin opacity from zero to one. |
orientation | str | ``vertical`` or ``horizontal`` orientation. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.ecdf
An empirical cumulative distribution function.
Props
| Prop | Type | Description |
|---|---|---|
values | Union[str, ArrayLike, None] | Sample values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
bins | Optional[int] | Optional bounded number of evaluation bins. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Line color. |
width | float | Line width in pixels. |
opacity | float | Line opacity from zero to one. |
dash | Union[str, Sequence[float], None] | Optional line dash pattern. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.heatmap
A rectangular heatmap from a two-dimensional matrix.
Props
| Prop | Type | Description |
|---|---|---|
z | Union[str, ArrayLike, None] | Two-dimensional values or a column name resolved from ``data``. |
x | Union[str, ArrayLike, None] | Optional x coordinates or a column name. |
y | Union[str, ArrayLike, None] | Optional y coordinates or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
name | Optional[str] | Series label used by legends and tooltips. |
colormap | channels.ColormapLike | Colormap used for cell values. |
domain | Optional[tuple[float, float]] | Explicit minimum and maximum for the color scale. |
opacity | float | Cell opacity from zero to one. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.hexbin
A native-kernel binned hexagonal density plot.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Y values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
gridsize | int | tuple[int, int] | Horizontal and optional vertical bin counts. |
range | Optional[tuple[tuple[float, float], tuple[float, float]]] | Explicit x and y input ranges. |
bins | str | Bin normalization mode. |
C | Union[str, ArrayLike, None] | Optional values aggregated within each hexagon. |
reduce_C_function | Callable[[np.ndarray], Scalar] | Reduction applied to values in each hexagon. |
mincnt | Optional[int] | Minimum observations required to render a hexagon. |
name | Optional[str] | Series label used by legends and tooltips. |
colormap | channels.ColormapLike | Colormap used for bin values. |
opacity | float | Hexagon opacity from zero to one. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.contour
Regular-grid isolines, optionally with a filled density surface.
Props
| Prop | Type | Description |
|---|---|---|
z | Union[str, ArrayLike, None] | Two-dimensional scalar grid or a column name. |
x | Union[str, ArrayLike, None] | Optional x coordinates or a column name. |
y | Union[str, ArrayLike, None] | Optional y coordinates or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
levels | Union[int, ArrayLike] | Number or explicit values of contour levels. |
filled | bool | Whether to fill intervals between contours. |
name | Optional[str] | Series label used by legends and tooltips. |
colormap | channels.ColormapLike | Colormap used for contour values. |
color | Any | Constant isoline color or direct RGBA colors cycled by level. |
width | Any | Isoline width in pixels, scalar or cycled by contour level. |
opacity | float | Contour opacity from zero to one. |
dash_negative | bool | Whether negative isolines use a dashed stroke. |
extend | str | Whether filled contours paint values below or above the levels. |
corner_mask | bool | Preserve the valid triangle of a quad with one missing corner. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.errorbar
Vertical and/or horizontal uncertainty bars.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Y values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
yerr | Union[str, Scalar, ArrayLike, None] | Symmetric or asymmetric vertical error values. |
xerr | Union[str, Scalar, ArrayLike, None] | Symmetric or asymmetric horizontal error values. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Error-bar color. |
width | float | Stroke width in pixels. |
cap_size | Optional[float] | Optional cap length in pixels. |
opacity | float | Stroke opacity from zero to one. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
key | Any | Stable row identities, or a column name resolved from ``data``. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.error_band
A confidence or error band between lower and upper series.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
lower | Union[str, ArrayLike, None] | Lower-bound values or a column name. |
upper | Union[str, ArrayLike, None] | Upper-bound values or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Band color. |
opacity | float | Band opacity from zero to one. |
line_width | float | Boundary-line width in pixels. |
line_opacity | float | Boundary-line opacity from zero to one. |
fill | Union[str, dict[str, str], None] | CSS fill value or linear gradient. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
key | Any | Stable row identities, or a column name resolved from ``data``. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.step
A stepped line series.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Y values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
where | str | Position of each step transition. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Line color. |
width | float | Line width in pixels. |
opacity | float | Line opacity from zero to one. |
dash | Union[str, Sequence[float], None] | Optional line dash pattern. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.stairs
A precomputed stairs series from values and bin edges.
Props
| Prop | Type | Description |
|---|---|---|
values | Union[str, ArrayLike, None] | Step heights or a column name resolved from ``data``. |
edges | Union[str, ArrayLike, None] | Bin-edge values or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
where | str | Position of each step transition. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Line color. |
width | float | Line width in pixels. |
opacity | float | Line opacity from zero to one. |
dash | Union[str, Sequence[float], None] | Optional line dash pattern. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.stem
A stem plot with optional point markers.
Props
| Prop | Type | Description |
|---|---|---|
x | Union[str, ArrayLike, None] | X values or a column name resolved from ``data``. |
y | Union[str, ArrayLike, None] | Y values or a column name resolved from ``data``. |
data | TableLike | Table used to resolve column-name inputs. |
base | Union[str, Scalar, ArrayLike] | Baseline value, values, or a column name. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Optional[str] | Stem and marker color. |
width | float | Stem width in pixels. |
opacity | float | Mark opacity from zero to one. |
marker | bool | Whether to draw a marker at each stem endpoint. |
marker_size | float | Marker size in pixels. |
symbol | str | Marker symbol name. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.segments
Independent line segments rendered as one instanced mark.
Props
| Prop | Type | Description |
|---|---|---|
x0 | Union[str, ArrayLike, None] | Starting x coordinates or a column name. |
y0 | Union[str, ArrayLike, None] | Starting y coordinates or a column name. |
x1 | Union[str, ArrayLike, None] | Ending x coordinates or a column name. |
y1 | Union[str, ArrayLike, None] | Ending y coordinates or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
name | Optional[str] | Series label used by legends and tooltips. |
color | Union[str, ColorLike, ArrayLike, None] | Constant color, values, or a column name. |
colormap | channels.ColormapLike | Color ramp for continuous values — a built-in name, a CSS ``linear-gradient(...)``, or a sequence of CSS colors (optionally ``(position, color)`` pairs). |
domain | Optional[tuple[float, float]] | Explicit minimum and maximum for continuous colors. |
width | Any | Segment width in pixels. |
opacity | Any | Segment opacity from zero to one. |
dash | Union[str, Sequence[float], None] | Optional line dash pattern. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.ribbon
Flow bands: a vertical span at `x0` joined to one at `x1` by a cubic.
Props
| Prop | Type | Description |
|---|---|---|
x0 | Union[str, ArrayLike, None] | Source face x coordinates or a column name. |
x1 | Union[str, ArrayLike, None] | Target face x coordinates or a column name. |
source_lo | Union[str, ArrayLike, None] | Lower edge of the span at `x0`. |
source_hi | Union[str, ArrayLike, None] | Upper edge of the span at `x0`. |
target_lo | Union[str, ArrayLike, None] | Lower edge of the span at `x1`. |
target_hi | Union[str, ArrayLike, None] | Upper edge of the span at `x1`. |
data | TableLike | Table used to resolve column-name inputs. |
color | Union[str, ColorLike, ArrayLike, None] | Source-end colour(s). |
color_target | Union[str, ColorLike, ArrayLike, None] | Target-end colour(s); omit for a flat band. |
colormap | channels.ColormapLike | Ramp for continuous colour values. |
name | Optional[str] | Series label used by legends and tooltips. |
opacity | Any | Band fill opacity from zero to one. |
stroke | Any | Optional band outline colour. |
stroke_width | Any | Band outline width in pixels. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
xy.sankey
A Sankey flow diagram from ``(source, target, value)`` links.
Props
| Prop | Type | Description |
|---|---|---|
links | Any | ``(source, target, value)`` triples; endpoints are node names. |
nodes | Optional[Sequence[Any]] | Explicit node order. Defaults to first appearance in `links`. |
node_width | float | Node rectangle width as a fraction of the diagram. |
node_padding | float | Vertical gap between nodes in a layer, as a fraction. |
align | str | ``"justify"`` (default) flushes sinks to the last layer. |
iterations | int | Crossing-minimisation sweeps. |
colors | Optional[Sequence[str]] | One CSS colour per node, in node order. |
link_opacity | Any | Ribbon opacity; node rectangles stay opaque. |
labels | bool | Draw node names beside the nodes. |
label_size | float | Node label font size in px. |
style | Optional[dict[str, StyleValue]] | Style overrides for the link ribbons. |
xy.funnel
A funnel mark: one centered segment per stage, in declared order.
Props
| Prop | Type | Description |
|---|---|---|
stage | Union[str, ArrayLike, None] | Stage names in order, or a column name resolved from ``data``. |
value | Union[str, ArrayLike, None] | One non-negative value per stage, or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
key | Any | Stable per-stage identities for animation matching, or a column name. Defaults to positional matching. |
orientation | str | ``"vertical"`` stacks stages along y (stage 0 on top in `funnel_chart`); ``"horizontal"`` runs them along x. |
geometry | str | ``"area"`` draws the classic tapering silhouette (each segment's far edge previews the next stage, so painted area is NOT proportional to the value); ``"bar"`` draws centered constant-width segments whose widths carry the values exactly. |
gap | Optional[float] | Gap between segments as a fraction of the stage pitch, in ``[0, 1)``. ``None`` resolves per geometry: 0 for ``"area"`` (a continuous silhouette), 0.2 for ``"bar"`` (bar-chart spacing). |
neck | str | Last area segment's far edge: ``"rect"`` holds the stage's own width, ``"taper"`` runs it to a point. Area geometry only. |
min_width | float | Drawn-width floor as a fraction of the widest stage, in ``[0, 1]``. Keeps zero/tiny stages visible and hoverable; values in labels, tooltips and events are never clamped. |
color | Optional[str] | One constant CSS color for every segment (no per-stage legend). |
colors | Optional[Sequence[str]] | One CSS color per stage. Defaults to the palette cycle in declared stage order. |
name | Optional[str] | Series label. Legend rows normally come from the per-stage categorical encoding instead. |
opacity | Any | Segment opacity from zero to one (per-trace). |
stroke | Any | Optional segment outline color (per-trace). |
stroke_width | Any | Segment outline width in pixels (per-trace). |
show_values | bool | Draw the value label on each segment. |
show_conversion | bool | Append the overall conversion (share of the first stage) to each value label. |
show_dropoff | bool | Draw the signed stage-over-stage change at each boundary (``-38%`` for a drop, ``+12%`` for growth). |
labels | bool | Master switch for all funnel labels. |
label_size | float | Label font size in px. |
value_format | str | ``str.format`` template for values. |
percent_format | str | ``str.format`` template for ratios. |
animation | Animation | bool | None | Per-mark animation override; ``False`` disables animation. |
style | Optional[dict[str, StyleValue]] | Mark style overrides (opacity, stroke, stroke-width). |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
xy.triangle_mesh
Filled triangle mesh with constant or per-triangle color values.
Props
| Prop | Type | Description |
|---|---|---|
x0 | Union[str, ArrayLike, None] | First-vertex x coordinates or a column name. |
y0 | Union[str, ArrayLike, None] | First-vertex y coordinates or a column name. |
x1 | Union[str, ArrayLike, None] | Second-vertex x coordinates or a column name. |
y1 | Union[str, ArrayLike, None] | Second-vertex y coordinates or a column name. |
x2 | Union[str, ArrayLike, None] | Third-vertex x coordinates or a column name. |
y2 | Union[str, ArrayLike, None] | Third-vertex y coordinates or a column name. |
data | TableLike | Table used to resolve column-name inputs. |
color | Union[str, ColorLike, ArrayLike, None] | Constant color, values, or a column name. |
colormap | channels.ColormapLike | Color ramp for continuous values — a built-in name, a CSS ``linear-gradient(...)``, or a sequence of CSS colors (optionally ``(position, color)`` pairs). |
domain | Optional[tuple[float, float]] | Explicit minimum and maximum for continuous colors. |
name | Optional[str] | Series label used by legends and tooltips. |
opacity | Any | Triangle opacity from zero to one. |
stroke | Any | Optional triangle outline color. |
stroke_width | Any | Triangle outline width in pixels. |
_joined_fill | bool | Internal pyplot hint for suppressing shared triangle edges. |
style | Optional[dict[str, StyleValue]] | Mark style overrides. |
class_name | Optional[str] | Adapter-only trace metadata; it does not style canvas geometry. |
x_axis | str | Identifier of the x axis used by this mark. |
y_axis | str | Identifier of the y axis used by this mark. |
FAQ
How do I combine multiple marks in one chart in Python?
Pass several mark factories as children of one chart container, e.g.
xy.line_chart(xy.area(...), xy.line(...), xy.scatter(...)). Give each mark a
name= for the legend, and pass data= once on the chart to share a table
across marks (a mark-level data= overrides it).
How do I control which mark draws on top of another?
Marks render in declaration order: later children paint over earlier ones. Put
broad fills such as xy.area() first and overlays such as xy.line() or
xy.scatter() after them.
How do I style each series differently in one chart?
Every mark takes its own paint options — for example xy.line(..., color=...)
or a style= dict of CSS declarations compiled for WebGL, SVG, and native
raster output. CSS selectors, Tailwind classes, and class_name= cannot paint
canvas or WebGL geometry, so per-series styling always goes through the mark
itself.
Can I plot a mark against a second y-axis?
Yes — bind the mark with y_axis="y2" (or x_axis= for x) and add a matching
xy.y_axis(id="y2", side="right") component to the chart. X-axis identifiers
must start with x and y-axis identifiers with y, and every named binding
needs a matching axis component.