Axes in Python
Add x_axis() and y_axis() children when a chart needs an explicit scale or
presentation contract. Without them, XY infers ordinary numeric, datetime, and
categorical behavior from the bound data.
Label the Axes and Fix the Domain
The most common axis contract is a label, an explicit domain=(min, max), and
a requested tick_count= so the view stays put regardless of the data:
Set the Scale Contract
Use type_="linear", "time", or "log" when inference is not the desired
contract. Explicit domains must be finite and increasing; log domains must also
be positive. reverse=True changes display direction without rewriting the
source values.
Control Labels and Ticks
Use a requested tick count for an adaptive axis, or provide exact tick values and matching labels:
Formatting, label placement, rotation, minimum gaps, and collision strategy let the renderer adapt the axis to a dashboard or publication layout. Exact option names and defaults are in the generated component reference.
Here the x-axis carries category names with tick_values= + tick_labels=,
rotated with tick_label_angle= and anchored at their ends, while
label_position= and label_offset= move the axis title out of the way:
Bind Marks to Named Axes
Use named axes for different units in one panel. An x-axis identifier must
start with x and a y-axis identifier with y; every named binding must have a
matching axis component.
Named axes compose with every mark kind. Below, monthly rain probability rides
a right-hand percentage axis (id="y2", side="right", format=".0%") while
temperature keeps the primary y-axis:
Style Axes
Axis style= uses a validated, cross-renderer vocabulary for grid, axis, tick,
and label paint and geometry. Browser DOM labels can additionally be targeted
through the chart's tick_label and axis_title slots. Use the validated axis
style for output that must agree across HTML, SVG, and native PNG.
For the scale model, including datetime and category handling, see Axes and scales. For styling, see Customize Each Part.
API Reference
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. |
FAQ
How do I set the axis range in Python?
Pass domain=(min, max) to xy.x_axis() or xy.y_axis(), e.g.
xy.y_axis(domain=(0, 100)). Explicit domains must be finite and increasing,
and a type_="log" axis additionally requires a positive domain.
How do I rotate or format axis tick labels?
Use format= with a numeric format string (e.g.
xy.x_axis(format=",.0f") or format=".0%") and tick_label_angle= to rotate
the labels. For full control, supply exact tick_values= with matching
tick_labels= strings instead of the adaptive tick_count=.
How do I add a second y-axis to a chart?
Declare a named axis such as xy.y_axis(id="y2", side="right") and bind marks
to it with y_axis="y2". Y-axis identifiers must start with y (x identifiers
with x), and every named binding needs a matching axis component in the
chart.
How do I reverse an axis in Python?
Pass reverse=True, e.g. xy.y_axis(domain=(0, 100), reverse=True). This
flips the display direction only — the source data values are not rewritten.