Axis Labels¶
dbt Charts keeps the encoded axis time unit stable while adapting crowded x-axis labels. Bucketed temporal axes first choose the finest fitting label format, then thin visibility, then tilt the labels that remain. Font size does not change.
Automatic layout¶
The renderer resolves label layout from the axis type, available width, and formatted label widths:
| Axis | Automatic behavior |
|---|---|
| Quantitative x-axis | Keep labels horizontal and let Vega-Lite place ticks (override the density with ticks.count or ticks.step) |
| Bucketed temporal x-axis | Choose the finest fitting calendar vocabulary, thin its visibility if needed, then tilt |
| Cyclic temporal x-axis | Drop alternating labels, then tilt if needed |
| Categorical x-axis | Keep every label, then tilt if needed |
| Horizontal bar category axis | Keep labels horizontal |
Daily axes and detected weekly axes first use compact day-number labels. Daily labels can step from every day to Mondays, then to month text, on bar, step, line, and area charts alike. Continuous line, area, and scatter axes measure the whole calendar span, so days with no row don't change their labels. Weekly labels step from every week to month text. Continuous weekly line and area axes keep Vega's tick positions but label each Sunday boundary with the represented ISO Monday bucket. After that vocabulary is chosen, visibility thinning follows meaningful calendar periods. Monthly text, for example, can appear only at quarter-opening months. The fiscal year start month anchors quarter and year boundaries.
Automatic format promotion changes the default tick cadence but not the encoded data grain. Later width-dependent visibility thinning changes only which labels are visible. It does not change:
- the encoding
time_unit, - the underlying ticks, or
- the chart data.
An explicitly authored labels.time_unit is different: it selects both the
label vocabulary and the default tick cadence. For example,
labels.time_unit: yearquarter on monthly data emits quarter labels and quarter
ticks. Author axis_x.ticks to override that default on a continuous temporal
axis.
If the thinned labels still collide, dbt Charts tries the configured
tilt_increments from the shallowest angle to the steepest.
Configure overlap resolution¶
labels.overlap has two boolean switches. Their execution order is fixed:
skip, then tilt.
style: axis_x: labels: overlap: skip: true tilt: true
Disable tilt to keep retained labels horizontal:
style: axis_x: labels: overlap: skip: true tilt: false
Disable both strategies to keep every label visible even when labels collide:
style: axis_x: labels: overlap: skip: false tilt: false
An explicit labels.angle takes precedence and bypasses automatic overlap
resolution:
style: axis_x: labels: angle: -45
Temporal labels¶
axis_x.time_unit controls the data encoding grain. The resolved
labels.time_unit controls the label text format and default tick cadence,
whether it was authored or chosen automatically. Automatic daily labels use the
finest fitting format on every daily axis; weekly labels use the same compact
vocabulary on continuous line and area axes. Width-dependent visibility
thinning after format selection changes neither the format nor ticks.
style: axis_x: time_unit: yearmonth fiscal_year_start_month: 3 labels: time_unit: yearmonth
For this axis, labels still use month text. When space is tight, only the fiscal-quarter opening months are shown: March, June, September, and December. The axis remains monthly.
Cyclic units such as monthofyear, dayofweek, and hourofday do not have a
coarser chronological period. They use alternating-label thinning before tilt.
See Time Axes for time-unit detection, formatting, and fiscal calendar behavior.
Tilt candidates¶
Themes configure the angles considered after thinning with
tilt_increments:
style: charts: axis_x: labels: tilt_increments: [0, -30, -45, -60, -90]
Order matters. dbt Charts uses the first angle whose projected width fits. This
is a theme-level knob; chart authors normally use labels.angle when they need
one exact rotation.
Bar orientation¶
With style.orientation: auto, categorical bar charts render horizontally.
Their category labels move to the y-axis and remain horizontal. Temporal,
quantitative, and time-unit-bucketed bars remain vertical.
Set an orientation explicitly to override that choice:
charts: revenue_by_state: type: bar x: state_name y: revenue style: orientation: vertical
Other label controls¶
Hide labels:
style: axis_y: labels: visible: false
Control truncation:
style: axis_x: labels: max_width: 240
Add a minimum gap between adjacent labels:
style: axis_x: labels: min_gap: 24
Align labels with labels.align. On a horizontal bar, the category names sit in
a column beside the plot, as wide as the longest name. Name the category axis
axis_x and the value axis axis_y: axis_x.labels.visible: false hides the
category names, and axis_y.labels.visible: false hides the value numbers.
style: orientation: horizontal axis_x: labels: align: center
align |
Where each name sits in the label column |
|---|---|
left |
Flush with the column's left edge |
center |
Centered in the column |
right |
Flush with the column's right edge |
inward |
Flush with the edge beside the plot |
outward |
Flush with the edge away from the plot |
inward and outward follow the axis: with the category axis on the left,
inward is right and outward is left.
Set value labels above their gridlines:
style: axis_y: labels: position: above_gridline
position: above_gridline sets each value label just above its gridline, with
the gridline running under it to the edge of the label gutter. The gutter keeps
its width, labels keep their alignment and number format, value tick marks are
not painted, and marks never reach the labels. The default, beside_gridline,
centers each label on the end of its gridline. position applies only where value gridlines
are horizontal: it has no effect on a band y axis, a horizontal bar, rotated
labels, or when gridlines are hidden.
Conditional label colors¶
A style.conditional rule can color x-axis labels with axis_x.labels.font.color, beside or instead of its marks style. It works on line, area, bar, scatter and heatmap charts.
type: line x: month y: revenue style: conditional: revenue: - lt: 1500000 axis_x: labels: font: color: negative.text - gte: 1500000 axis_x: labels: font: color: positive.text
- A rule on the x column tests each label's own value: its category, or on a time axis the start of the period it names (
Q2is April 1). A year column is a date axis, so test it with a date (gte: 2022-01-01), as for its marks. - A rule on any other column tests the rows the label names. Their values must agree: a label over rows that differ (month labels over weekly rows, or several series at one x) is refused, as is a label sitting between two of the data's buckets. On a multi-y chart a rule on a
y:column reads only that measure's rows, and only one column may color the labels. - A label with no row keeps its color.
- Refused outright: a numeric x axis, a scatter's non-date x, a heatmap's date x and a faceted heatmap. A continuous time axis (a date scatter, a bar on a time scale) takes only rules on the x column.
Mirrored Y-Axis¶
Set style.axis_y.mirror: true on a wide cartesian chart to draw the y-scale
on both the left and right edges. Both edges share the same scale and ticks.
This is a readability aid, not a second scale.
source: examples_db
charts:
revenue_wide:
query:
sql: |
SELECT DATE_TRUNC('week', date) AS week, SUM(revenue) AS revenue
FROM ecommerce_orders
GROUP BY week
ORDER BY week
type: line
title: Weekly Revenue
x: week
y: revenue
style:
axis_y:
mirror: true
rows:
- revenue_wide
Pass an object instead of true to relabel the mirrored edge:
style: axis_y: mirror: format: ".0%"
format and expr are mutually exclusive. Neither changes the scale or tick
placement.
format also accepts an object with spec, prefix and suffix keys for
a unit the board's regional: currency
cannot express, such as a second currency; see
the object form
in the styling guide.
This differs from a layered chart with independent left and right axes. A mirrored axis draws one scale twice.