Marks and Components

Learning
- Overview
- Core Concepts
- Styling
- Advanced
Charts
- Overview
- Core Charts
- Distributions
- Density & Fields
- Specialized
- Polar Charts
- Components
Other

These tables are generated from XY's public Python signatures and docstrings. Use the Components guides for composition patterns, then return here for exact parameter names, types, and defaults.

Marks

Marks accept arrays directly or resolve column names through mark-level or chart-level data=. The hist() convenience wrapper accepts the same parameters and produces the same histogram mark as histogram().

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.

Axes and Annotations

Axes configure scale presentation and named coordinate systems. Annotations add rules, bands, text, markers, arrows, thresholds, and callouts. threshold and threshold_zone are annotation conveniences, not data marks.

xy.x_axis

Configure an x axis.

Props

Prop	Type	Description
`id`	`str`	Axis identifier referenced by marks.
`label`	`Optional[str]`	Axis label.
`label_position`	`Optional[AxisLabelPosition]`	Named or structured label placement.
`label_offset`	`Optional[float]`	Label offset in pixels.
`label_angle`	`Optional[float]`	Label rotation in degrees.
`type_`	`Optional[str]`	Scale type, such as ``linear``, ``time``, ``log``, or ``symlog``.
`constant`	`Optional[float]`	Width of the linear region around zero for ``symlog``.
`domain`	`Optional[tuple[float, float]]`	Explicit minimum and maximum scale values.
`margin`	`Optional[float]`	Fractional padding around an automatic domain.
`bounds`	`Union[tuple[float, float], Literal['data'], None]`	Hard navigation limits, or ``"data"`` to use the data range. Pan and zoom are clamped within these limits; ``None`` leaves navigation unrestricted.
`reverse`	`bool`	Whether to reverse the scale direction.
`format`	`Optional[str]`	Tick-label format string.
`tick_count`	`Optional[int]`	Requested number of ticks.
`tick_values`	`Union[Sequence[float], np.ndarray, None]`	Explicit tick positions.
`minor_tick_values`	`Union[Sequence[float], np.ndarray, None]`	Explicit unlabeled minor tick positions.
`tick_labels`	`Optional[Sequence[str]]`	Labels corresponding to explicit tick positions.
`tick_label_angle`	`Optional[float]`	Tick-label rotation in degrees.
`tick_label_strategy`	`Optional[AxisTickLabelStrategy]`	Collision-handling strategy for tick labels.
`tick_label_anchor`	`Optional[str]`	Which edge of a tick label pins to its tick — ``"start"``, ``"center"`` (default), or ``"end"`` (matplotlib's ``ha`` values ``"left"``/``"right"`` are accepted as aliases). With ``tick_label_angle``, the label rotates about the pinned edge, so an end-anchored slanted label hangs entirely below a bottom axis instead of seesawing around its midpoint.
`tick_label_min_gap`	`Optional[float]`	Minimum gap between tick labels in pixels.
`side`	`Optional[str]`	Side of the plot where the axis is drawn.
`tick_sides`	`Optional[Sequence[str]]`	Plot sides where tick marks are drawn. Defaults to ``side``; supplying both draws mirrored ticks without moving the axis labels.
`tick_label_sides`	`Optional[Sequence[str]]`	Plot sides where tick labels are drawn. Defaults to ``side`` and remains independent of ``tick_sides``.
`show`	`Optional[bool]`	Draw this axis at all. ``False`` hides its baseline, tick marks, tick labels, title, and grid lines in one switch; the four narrower switches below override it either way, so ``show=False, grid=True`` leaves only the grid.
`line`	`Optional[bool]`	Draw the axis baseline.
`ticks`	`Optional[bool]`	Draw the tick marks.
`grid`	`Optional[bool]`	Draw this axis's grid lines (the y axis owns the horizontal guides, the x axis the vertical ones).
`text`	`Optional[bool]`	Draw this axis's text — its tick labels and its title. (Unlike ``tick_labels``, which supplies the label strings.)
`style`	`Optional[dict[str, StyleValue]]`	Axis style overrides. An explicit property here always wins over the switches above.
`minor_style`	`Optional[dict[str, StyleValue]]`	Independent minor tick/grid style overrides.
`nonpositive`	`Optional[Literal['clip', 'mask']]`	Log-axis handling for non-positive mark coordinates: ``"clip"`` or ``"mask"``.

xy.y_axis

Configure a y axis.

Props

Prop	Type	Description
`id`	`str`	Axis identifier referenced by marks.
`label`	`Optional[str]`	Axis label.
`label_position`	`Optional[AxisLabelPosition]`	Named or structured label placement.
`label_offset`	`Optional[float]`	Label offset in pixels.
`label_angle`	`Optional[float]`	Label rotation in degrees.
`type_`	`Optional[str]`	Scale type, such as ``linear``, ``time``, ``log``, or ``symlog``.
`constant`	`Optional[float]`	Width of the linear region around zero for ``symlog``.
`domain`	`Optional[tuple[float, float]]`	Explicit minimum and maximum scale values.
`margin`	`Optional[float]`	Fractional padding around an automatic domain.
`bounds`	`Union[tuple[float, float], Literal['data'], None]`	Hard navigation limits, or ``"data"`` to use the data range. Pan and zoom are clamped within these limits; ``None`` leaves navigation unrestricted.
`reverse`	`bool`	Whether to reverse the scale direction.
`format`	`Optional[str]`	Tick-label format string.
`tick_count`	`Optional[int]`	Requested number of ticks.
`tick_values`	`Union[Sequence[float], np.ndarray, None]`	Explicit tick positions.
`minor_tick_values`	`Union[Sequence[float], np.ndarray, None]`	Explicit unlabeled minor tick positions.
`tick_labels`	`Optional[Sequence[str]]`	Labels corresponding to explicit tick positions.
`tick_label_angle`	`Optional[float]`	Tick-label rotation in degrees.
`tick_label_strategy`	`Optional[AxisTickLabelStrategy]`	Collision-handling strategy for tick labels.
`tick_label_anchor`	`Optional[str]`	Which edge of a tick label pins to its tick — ``"start"``, ``"center"``, or ``"end"`` (matplotlib's ``ha`` values ``"left"``/``"right"`` are accepted as aliases). Unset defaults to the tick-side edge: ``"end"`` for a left-side axis, ``"start"`` for a right-side one. With ``tick_label_angle``, the label rotates about the pinned edge.
`tick_label_min_gap`	`Optional[float]`	Minimum gap between tick labels in pixels.
`side`	`Optional[str]`	Side of the plot where the axis is drawn.
`tick_sides`	`Optional[Sequence[str]]`	Plot sides where tick marks are drawn. Defaults to ``side``; supplying both draws mirrored ticks without moving the axis labels.
`tick_label_sides`	`Optional[Sequence[str]]`	Plot sides where tick labels are drawn. Defaults to ``side`` and remains independent of ``tick_sides``.
`show`	`Optional[bool]`	Draw this axis at all. ``False`` hides its baseline, tick marks, tick labels, title, and grid lines in one switch; the four narrower switches below override it either way, so ``show=False, grid=True`` leaves only the grid.
`line`	`Optional[bool]`	Draw the axis baseline.
`ticks`	`Optional[bool]`	Draw the tick marks.
`grid`	`Optional[bool]`	Draw this axis's grid lines (the y axis owns the horizontal guides, the x axis the vertical ones).
`text`	`Optional[bool]`	Draw this axis's text — its tick labels and its title. (Unlike ``tick_labels``, which supplies the label strings.)
`style`	`Optional[dict[str, StyleValue]]`	Axis style overrides. An explicit property here always wins over the switches above.
`minor_style`	`Optional[dict[str, StyleValue]]`	Independent minor tick/grid style overrides.
`nonpositive`	`Optional[Literal['clip', 'mask']]`	Log-axis handling for non-positive mark coordinates: ``"clip"`` or ``"mask"``.

xy.theta_axis

Configure the angular axis of an `xy.polar_chart`.

Props

Prop	Type	Description
`unit`	`Optional[str]`	Angular unit of the data, ``"radians"`` (default) or ``"degrees"``.
`zero`	`Union[str, float, None]`	Direction that angle 0 points — ``"E"`` (default), ``"N"``, ``"W"``, ``"S"``, or an angle in radians counterclockwise from east.
`direction`	`Optional[str]`	``"counterclockwise"`` (default) or ``"clockwise"``. Compass work usually wants ``zero="N"`` with ``"clockwise"``, which puts 90° at east and 180° at south.
`sector`	`Optional[tuple[float, float]]`	Visible angular interval in the declared ``unit``. The sweep must be increasing and no wider than one full turn.
`grid_shape`	`Optional[str]`	``"circular"`` (default) for arc rings or ``"linear"`` for polygonal rings joining the angular spokes.
`**kwargs`	`Any`	Any `x_axis` keyword.

xy.r_axis

Configure the radial axis of an `xy.polar_chart`.

Props

Prop	Type	Description
`hole`	`Optional[float]`	Display-space inner-radius fraction, from 0 (no hole) up to but excluding 1.
`origin`	`Optional[float]`	Data-space radial origin. An origin below the visible radial minimum creates an annulus. Mutually exclusive with ``hole``.
`**kwargs`	`Any`	Any `y_axis` keyword.

xy.vline

A vertical rule annotation at an x coordinate or x-axis category.

Props

Prop	Type	Description
`x`	`CoordinateLike`	X coordinate or category where the rule is drawn.
`text`	`Optional[str]`	Optional label displayed beside the rule.
`color`	`Optional[str]`	Rule color.
`width`	`float`	Rule width in pixels.
`opacity`	`float`	Rule opacity from zero to one.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The rule is canvas-painted and is styled through ``color``, ``width``, and ``opacity``.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.hline

A horizontal rule annotation at a y coordinate or y-axis category.

Props

Prop	Type	Description
`y`	`CoordinateLike`	Y coordinate or category where the rule is drawn.
`text`	`Optional[str]`	Optional label displayed beside the rule.
`color`	`Optional[str]`	Rule color.
`width`	`float`	Rule width in pixels.
`opacity`	`float`	Rule opacity from zero to one.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The rule is canvas-painted and is styled through ``color``, ``width``, and ``opacity``.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.x_band

A vertical span annotation between two x coordinates or categories.

Props

Prop	Type	Description
`x0`	`CoordinateLike`	Starting x coordinate or category.
`x1`	`CoordinateLike`	Ending x coordinate or category.
`text`	`Optional[str]`	Optional label displayed in the band.
`color`	`Optional[str]`	Band color.
`opacity`	`float`	Band opacity from zero to one.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The band is canvas-painted and is styled through ``color`` and ``opacity``.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.y_band

A horizontal span annotation between two y coordinates or categories.

Props

Prop	Type	Description
`y0`	`CoordinateLike`	Starting y coordinate or category.
`y1`	`CoordinateLike`	Ending y coordinate or category.
`text`	`Optional[str]`	Optional label displayed in the band.
`color`	`Optional[str]`	Band color.
`opacity`	`float`	Band opacity from zero to one.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The band is canvas-painted and is styled through ``color`` and ``opacity``.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.threshold

A semantic threshold rule on the x or y axis.

Props

Prop	Type	Description
`value`	`CoordinateLike`	Coordinate or category where the threshold is drawn.
`axis`	`str`	Axis receiving the threshold, ``x`` or ``y``.
`text`	`Optional[str]`	Optional threshold label.
`color`	`Optional[str]`	Rule color.
`width`	`float`	Rule width in pixels.
`opacity`	`float`	Rule opacity from zero to one.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The threshold rule is canvas-painted.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.threshold_zone

A semantic threshold band on the x or y axis.

Props

Prop	Type	Description
`start`	`CoordinateLike`	Starting coordinate or category.
`end`	`CoordinateLike`	Ending coordinate or category.
`axis`	`str`	Axis receiving the band, ``x`` or ``y``.
`text`	`Optional[str]`	Optional threshold label.
`color`	`Optional[str]`	Band color.
`opacity`	`float`	Band opacity from zero to one.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The threshold band is canvas-painted.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.text

A text annotation anchored at an x/y coordinate or category.

Props

Prop	Type	Description
`x`	`CoordinateLike`	Anchor x coordinate or category.
`y`	`CoordinateLike`	Anchor y coordinate or category.
`value`	`str`	Text to display.
`dx`	`float`	Horizontal pixel offset from the anchor.
`dy`	`float`	Vertical pixel offset from the anchor.
`color`	`Optional[str]`	Text color.
`anchor`	`str`	Text alignment relative to the anchor point.
`class_name`	`Optional[str]`	DOM class applied to the text label.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.label

Create a positioned text label.

Props

Prop	Type	Description
`x`	`CoordinateLike`	Anchor x coordinate or category.
`y`	`CoordinateLike`	Anchor y coordinate or category.
`value`	`str`	Text to display.
`dx`	`float`	Horizontal pixel offset from the anchor.
`dy`	`float`	Vertical pixel offset from the anchor.
`color`	`Optional[str]`	Text color.
`anchor`	`str`	Text alignment relative to the anchor point.
`class_name`	`Optional[str]`	DOM class applied to the text label.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.marker

A point marker annotation with an optional label.

Props

Prop	Type	Description
`x`	`CoordinateLike`	Marker x coordinate or category.
`y`	`CoordinateLike`	Marker y coordinate or category.
`text`	`Optional[str]`	Optional marker label.
`color`	`Optional[str]`	Marker fill color.
`size`	`float`	Marker size in pixels.
`symbol`	`str`	Marker symbol name.
`stroke_color`	`Optional[str]`	Marker outline color.
`stroke_width`	`float`	Marker outline width in pixels.
`opacity`	`float`	Marker opacity from zero to one.
`dx`	`float`	Horizontal label offset in pixels.
`dy`	`float`	Vertical label offset in pixels.
`anchor`	`str`	Label alignment relative to the marker.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The marker is canvas-painted and is styled through its marker arguments.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.arrow

An arrow annotation from one data coordinate to another.

Props

Prop	Type	Description
`x0`	`CoordinateLike`	Starting x coordinate or category.
`y0`	`CoordinateLike`	Starting y coordinate or category.
`x1`	`CoordinateLike`	Ending x coordinate or category.
`y1`	`CoordinateLike`	Ending y coordinate or category.
`text`	`Optional[str]`	Optional arrow label.
`color`	`Optional[str]`	Arrow color.
`width`	`float`	Arrow width in pixels.
`opacity`	`float`	Arrow opacity from zero to one.
`class_name`	`Optional[str]`	DOM class applied to the optional text label. The arrow is canvas-painted and is styled through ``color``, ``width``, and ``opacity``.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

xy.callout

A text callout offset from a data coordinate with a pointer arrow.

Props

Prop	Type	Description
`x`	`CoordinateLike`	Anchor x coordinate or category.
`y`	`CoordinateLike`	Anchor y coordinate or category.
`value`	`str`	Callout text.
`dx`	`float`	Horizontal pixel offset from the anchor.
`dy`	`float`	Vertical pixel offset from the anchor.
`color`	`Optional[str]`	Callout color.
`width`	`float`	Pointer width in pixels.
`opacity`	`float`	Callout opacity from zero to one.
`anchor`	`str`	Text alignment relative to the callout point.
`class_name`	`Optional[str]`	DOM class applied to the callout text. The pointer is canvas-painted.
`style`	`Optional[dict[str, StyleValue]]`	Annotation style overrides.

Chrome and Behavior

Chrome components configure legends, tooltips, inferred colorbars, the modebar, theme tokens, and interaction behavior. colorbar() derives its domain and colormap from the last supported continuous mark, while title, ticks, and orientation control its presentation.

xy.legend

Configure chart legend chrome.

Props

Prop	Type	Description
`*children`	`Any`	Optional opaque replacement content.
`show`	`bool`	Whether to display the legend.
`loc`	`Optional[str]`	Legend placement within or around the plot.
`anchor`	`Optional[tuple[float, ...]]`	Two- or four-value normalized plot-coordinate anchor.
`ncols`	`int`	Number of legend columns.
`title`	`Optional[str]`	Optional legend title.
`highlight`	`bool`	Whether hovering a legend entry emphasizes its series by dimming the others (live client only; exports are static).
`toggle`	`bool`	Whether clicking a legend entry hides/shows its series or category (live client only; exports are static).
`render`	`Any`	Opaque renderer supplied by an adapter.
`class_name`	`Optional[str]`	DOM class name applied to the legend.
`style`	`Optional[dict[str, StyleValue]]`	Legend style overrides.

Configure chart tooltip chrome.

Props

Prop	Type	Description
`*children`	`Any`	Optional opaque replacement content.
`show`	`bool`	Whether to display tooltips.
`render`	`Any`	Opaque renderer supplied by an adapter.
`fields`	`Optional[list[str]]`	Data fields shown in each tooltip.
`title`	`Optional[str]`	Optional tooltip title.
`format`	`Optional[dict[str, str]]`	Per-field value formats.
`labels`	`Optional[dict[str, str]]`	Display labels keyed by source field. Without ``fields``, they rename the matching default x/y/color/size rows. Formatting and title placeholders continue to use the source field names.
`class_name`	`Optional[str]`	DOM class name applied to the tooltip.
`style`	`Optional[dict[str, StyleValue]]`	Tooltip style overrides.

xy.colorbar

Configure color-scale chrome.

Props

Prop	Type	Description
`*children`	`Any`	Optional opaque replacement content.
`show`	`bool`	Whether to display the colorbar.
`render`	`Any`	Opaque renderer supplied by an adapter.
`title`	`Optional[str]`	Optional colorbar title. By default XY uses the color field or mark name when one is available.
`orientation`	`str`	``vertical`` or ``horizontal`` placement.
`ticks`	`Optional[list[float]]`	Optional finite numeric tick positions.
`class_name`	`Optional[str]`	DOM class name applied to the colorbar.
`style`	`Optional[dict[str, StyleValue]]`	Colorbar style overrides.

xy.modebar

Configure interactive chart controls.

Props

Prop	Type	Description
`show`	`bool`	Whether to display the modebar.
`class_name`	`Optional[str]`	DOM class name applied to the modebar.
`style`	`Optional[dict[str, StyleValue]]`	Modebar style overrides.
`button_class_name`	`Optional[str]`	DOM class name applied to each button.
`button_style`	`Optional[dict[str, StyleValue]]`	Style overrides applied to each button.

xy.theme

Configure chart theme tokens.

Props

Prop	Type	Description
`style`	`Optional[dict[str, StyleValue]]`	Base chart style overrides.
`background`	`Optional[StyleValue]`	Figure background color — paints the whole chart card including margins, title, and tick labels (matplotlib's ``figure.facecolor``). The plot rect shows through unless ``plot_background`` sets it separately.
`plot_background`	`Optional[StyleValue]`	Plot-area background color — the data rect only (matplotlib's ``axes.facecolor``).
`grid_color`	`Optional[StyleValue]`	Grid-line color.
`axis_color`	`Optional[StyleValue]`	Axis-line and tick color.
`text_color`	`Optional[StyleValue]`	Default chart text color.
`crosshair_color`	`Optional[StyleValue]`	Hover crosshair color.
`selection_color`	`Optional[StyleValue]`	Selection-outline color.
`selection_fill`	`Optional[StyleValue]`	Selection-region fill color.
`palette`	`Union[Sequence[str], Mapping[str, str], None]`	Categorical color cycle for this chart — the colors unnamed series take in order, and the colors a categorical ``color=`` channel assigns to its categories. Defaults to XY's CVD-safe eight-slot palette; a shorter list repeats (with a warning). A ``{category: color}`` mapping pins colors to category labels instead of positions, so a category keeps its color across marks and across facet panels — including panels where some categories are absent, which a positional cycle silently recolors. Categories the map does not name take the next unused default color (with a warning), and unnamed series cycle the map's values in order. Entries must be colors XY can resolve without a browser (hex, ``rgb()``, ``hsl()``, named), like colormap stops: a palette is indexed, and browser-only entries would collapse several categories onto one fallback color in exports and density surfaces.
`**tokens`	`StyleValue`	Additional supported theme tokens.

xy.interaction_config

Configure browser interaction chrome and event emission.

Props

Prop	Type	Description
`hover`	`Optional[bool]`	Whether pointer movement emits hover events.
`click`	`Optional[bool]`	Whether picked marks emit click events.
`select`	`Optional[bool]`	Whether shift-drag box selection is enabled.
`brush`	`Optional[bool]`	Whether brush selection is enabled.
`crosshair`	`Optional[bool]`	Whether plot-aligned hover guides are shown.
`navigation`	`Optional[bool]`	Whether pointer drag and wheel gestures pan or zoom the chart.
`pan`	`Optional[bool]`	Whether plain-drag pan is enabled. ``False`` ignores plain-drag pan gestures and contains every zoom-enabled axis to its home window. The default keeps panning enabled.
`pan_axes`	`Optional[tuple[str, ...]]`	Concrete declared axis IDs pan gestures translate freely. The default includes every declared axis. An excluded axis that zoom can still navigate is contained: its window slides inside the axis's home extents (plain drag keeps working on a zoomed-in view) but never extends past them, on any mutation path.
`zoom`	`Optional[bool]`	Whether viewport zoom is enabled. ``False`` ignores wheel and box zoom and hides the modebar zoom controls. The default keeps zooming enabled on Cartesian charts. Polar charts default it OFF — the centre of a disc is a fixed point, so zooming a pie, radial bar, gauge, or radar crops its rim instead of navigating it — except `wind_rose`, whose radius is a frequency count. Pass ``True`` here to opt a polar chart back in.
`default_drag_action`	`Optional[DefaultDragAction]`	Initial action performed by a plain plot drag. ``"auto"`` is the default and chooses pan first; ``"zoom"`` draws a rectangle and zooms to its bounds. Selection actions make their corresponding gesture the default without requiring Shift. The modebar can change the active action without changing this configured default.
`zoom_axes`	`Optional[tuple[str, ...]]`	Axis dimensions changed by wheel, modebar, and box zoom. Use ``("x",)`` for x-only zoom. Secondary IDs such as ``"y2"`` are independent. The default includes every declared axis.
`zoom_limits`	`Optional[ZoomLimits]`	Minimum and maximum magnification relative to the home range, either one pair for all zoom axes or a mapping by axis ID. Missing configuration defaults to ``(1.0, None)`` per zoom axis.
`wheel_zoom`	`Optional[bool]`	Whether wheel and trackpad zoom is available.
`box_zoom`	`Optional[bool]`	Whether box zoom is available as a drag action.
`zoom_buttons`	`Optional[bool]`	Whether toolbar Zoom In/Out commands are available.
`double_click_reset`	`Optional[bool]`	Whether double-click restores ``reset_axes``.
`reset_axes`	`Optional[tuple[str, ...]]`	Concrete declared axis IDs restored by reset. The default is the union of enabled pan and zoom axes.
`link_group`	`Optional[str]`	Identifier used to synchronize charts in the browser.
`link_axes`	`Optional[tuple[str, ...]]`	Axes synchronized within the link group.
`history`	`Optional[bool]`	Whether the client keeps a view-history stack with modebar Back/Forward buttons. Enabled by default; ``False`` removes the buttons and stops snapshotting.

xy.animation

Configure entrance and data-update motion without per-frame callbacks.

Props

Prop	Type	Description
`enabled`	`bool \| Literal['auto']`	``"auto"`` (default) honors reduced motion; a boolean explicitly enables or disables.
`delay`	`float`	Non-negative delay before motion begins, in milliseconds. Default ``0``.
`duration`	`float`	Non-negative animation duration, in milliseconds. Default ``400``.
`easing`	`str \| tuple[float, float, float, float] \| Spring`	Named easing, four-number cubic Bézier tuple, or ``spring()`` policy. Default ``"ease-out"``.
`match`	`Literal['index', 'append', 'key']`	Row identity strategy: ``"index"`` (default), ``"append"``, or ``"key"``.
`enter`	`str`	Entrance effect, such as ``"auto"`` (default), ``"scale"``, or ``"reveal"``.
`update`	`str`	Update effect; use ``"interpolate"`` (default) or ``"none"``.
`interpolate`	`Sequence[str]`	Unique channels to interpolate during updates. Default ``("position", "size", "color", "domain")``.
`on_start`	`Optional[Callable[[dict], None]]`	Optional live-host callback receiving the animation-start event.
`on_end`	`Optional[Callable[[dict], None]]`	Optional live-host callback receiving the animation-end event.

xy.spring

Build a serializable spring easing policy.

Props

Prop	Type	Description
`stiffness`	`float`	Spring stiffness; larger values respond more quickly.
`damping`	`float`	Resistance that settles the spring and limits overshoot.
`mass`	`float`	Spring mass; larger values respond more slowly.

For rendering boundaries, see Marks, Colorbars, and Modebars and interaction controls.

Learn

Gallery

API Reference

Learning

Charts

Other

Marks and Components

Marks

xy.line

Props

xy.scatter

Props

xy.area

Props

xy.bar

Props

xy.column

Props

xy.histogram

Props

xy.box

Props

xy.violin

Props

xy.ecdf

Props

xy.heatmap

Props

xy.hexbin

Props

xy.contour

Props

xy.errorbar

Props

xy.error_band

Props

xy.step

Props

xy.stairs

Props

xy.stem

Props

xy.segments

Props

xy.ribbon

Props

xy.sankey

Props

xy.funnel

Props

xy.triangle_mesh

Props

Axes and Annotations

xy.x_axis

Props

xy.y_axis

Props

xy.theta_axis

Props

xy.r_axis

Props

xy.vline

Props

xy.hline

Props

xy.x_band

Props

xy.y_band

Props

xy.threshold

Props

xy.threshold_zone

Props

xy.text

Props

xy.label

Props

xy.marker

Props

xy.arrow