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:
Show and Hide Axis Parts
Each axis takes five switches: show, line, ticks, grid, and text
(tick labels plus the axis title). show sets the other four; each of the four
overrides show, so a grid with no other chrome is one call.
The switches compile to ordinary axis style properties, so they work in HTML,
SVG, and native PNG alike, and an explicit style= property still wins over a
switch. text controls whether axis text is drawn; tick_labels= supplies
the label strings.
Style Axes
Axis style= uses a validated, cross-renderer vocabulary for grid, axis, tick,
and label paint and geometry. In the browser, axis_line, tick_mark,
tick_label, and axis_title target each visible Cartesian part, while
axis_band targets the invisible axis-only pan/zoom gesture region (most
usefully for cursor utilities). Each band exposes its full axis identifier
through data-xy-axis-band, such as x, y, x2, or y2. The utilities
below distinguish the two primary axes; add matching data variants for any
named axes in the chart. 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. |
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"``. |
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.