Marks and Components
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 | str | Colormap used for continuous color values. |
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. |
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 | float | Bar width 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. |
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 | float | Column width 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. |
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]] | 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.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 | str | 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 | str | 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 | str | Colormap used for contour values. |
color | Optional[str] | Constant isoline color. |
width | float | Isoline width in pixels. |
opacity | float | Contour opacity from zero to one. |
dash_negative | bool | Whether negative isolines use a dashed stroke. |
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 | str | Colormap used for continuous color values. |
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. |
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.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 | str | Colormap used for continuous color values. |
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. |
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. |
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. |
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. |
style | Optional[dict[str, StyleValue]] | Axis style overrides. |
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. |
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. |
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. |
style | Optional[dict[str, StyleValue]] | Axis style overrides. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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 name applied to the annotation. |
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. |
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. |
xy.tooltip
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. |
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. |
**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, double-click reset, and modebar zoom controls. The default keeps zooming enabled. |
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"`` honors reduced motion; a boolean explicitly enables or disables. |
delay | float | Non-negative delay before motion begins, in milliseconds. |
duration | float | Non-negative animation duration, in milliseconds. |
easing | str | tuple[float, float, float, float] | Spring | Named easing, four-number cubic Bézier tuple, or ``spring()`` policy. |
match | Literal['index', 'append', 'key'] | Row identity strategy: ``"index"``, ``"append"``, or ``"key"``. |
enter | str | Entrance effect, such as ``"auto"``, ``"scale"``, or ``"reveal"``. |
update | str | Update effect; use ``"interpolate"`` or ``"none"``. |
interpolate | Sequence[str] | Unique channels to interpolate during updates. |
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.