Chart Color Channels¶
dbt Charts supports color as the primary data channel at chart root.
color accepts a bare field name (string) to encode a column as series grouping.
A constant color goes on the chart's mark (style.marks.<mark>.color); gradient scales go under style.color.
Discrete, rule-driven styling lives in a separate block on the chart:
style.columns.<column>.conditional: on type: table, and style.conditional: on pie,
donut, heatmap, map and type: kpi charts (see
Conditional (threshold) below). A rule beside a color:
channel is allowed: it overrides the channel's color for the matching marks only,
and the legend is unchanged.
Shorthand¶
A plain string binds a column to the color channel:
color: segment
This is the only accepted form at chart root. color does not accept {column: ...}, {value: ...}, or {scale: ...} at chart root; use style.marks.<mark>.color for a constant color or style.color.gradient for a scale.
Literal¶
A constant color lives on the chart's primary mark, not in style.color. style.color only configures how a color: channel maps values to colors (categorical, gradient). A chart with no color: channel paints its mark with, in order: the mark's own color, single_series_palette, then the palette. A color: channel always wins.
style: marks: bar: color: "#1aff3c"
Each family has one primary mark:
| Chart type | Constant color |
|---|---|
bar, histogram |
style.marks.bar.color |
area |
style.marks.area.color |
line |
style.marks.line.stroke.color |
scatter, point_map, bubble_map |
style.marks.point.color |
pie, donut |
style.marks.slice.color |
heatmap |
style.marks.rect.color |
map, geoshape |
style.marks.geoshape.fill |
The same fields work under style.charts.<family>.marks in a theme or board. A table's cell text color is style.column_defaults.font.color.
Gradient scale¶
Map a numeric column to a continuous color range via style.color.gradient:
color: revenue style: color: gradient: palette: ["#ffffff", "#0000ff"] min: 0 max: 1000000
Omit min/max to scale from data: by default the domain is widened to round
bounds and every round tick is labeled on the legend; set nice: false for the
exact data extent instead. palette must be list[str] for color channels.
Conditional (threshold)¶
Available on type: table and type: kpi only.
Discrete, rule-driven styling goes on the column a table paints
(style.columns.<column>.conditional:, a list of rules; see
Tables) or, on a
KPI, under style.conditional: indexed by column name: a list of rules per
column. A KPI's rule styles the card: background, value.font, label.font,
support.font (color, weight) and support.tone.
Each rule has exactly one predicate and one or more style outputs:
| Predicate | Shape | Matches |
|---|---|---|
eq: x |
any scalar, min() or max() |
values equal to x (bool/int cross-match guarded) |
ne: x |
any scalar, min() or max() |
values not equal to x |
lt / lte / gt / gte |
number, date or aggregate | one-sided comparison; a number never matches a non-numeric cell, and a date requires date cells |
between: [low, high] |
two numbers or two dates (low <= high), or aggregates |
closed inclusive range; a computed empty range matches nothing |
in: [v1, v2, ...] |
non-empty list | equality against any list element |
is_null: true |
boolean | null/None values |
is_null: false |
boolean | any non-null value (including 0, "", false) |
default: true |
boolean | catch-all; fires when no other rule matched |
A date operand (gt: 2026-01-01, or a timestamp) compares each cell as a date. A non-null cell that is not a date or timestamp is an error, not a non-match.
type: table style: columns: arr: conditional: - between: [0, 1000000] background: "#dcfce7" - gt: 1000000 background: "#166534" font: color: "#ffffff" weight: bold - is_null: true background: "#e5e7eb" - default: true background: "#fee2e2" font: color: "#991b1b"
An operand can be an aggregate of the rule's own column: min(), max(),
avg(), median() or percentile(<0-100>). It is computed over every row of
the query result, not per series or per panel. eq and ne take only min()
or max(), which also work on a date column; the rest need a numeric column.
A column with no value matches no aggregate rule. A KPI or pivot table rule
takes no aggregate.
style: conditional: revenue: - eq: max() marks: bar: color: "#166534" - lt: percentile(25) marks: bar: color: "#991b1b"
Non-default rules are evaluated in list order; later matches override
earlier ones for overlapping style keys. A default: true rule must be the
last entry in its column's rules and only fires when no other rule matched
for the current row; it is a true fallback, not a last-match-wins override.
Without a default:, rows that match nothing fall back to the chart's
un-conditional styling.
Pattern fills¶
Hue alone cannot always tell series apart: in print, in grayscale, for color-blind
readers, or once a palette runs past its safe slots. The pattern channel fills
marks with textures (hatching, dots, dashes) so a series reads by texture as well
as by hue. It works on bar, area, pie, and donut charts, and on a heatmap
for a pattern ramp. Histograms, lines, and scatter charts do not take it.
pattern: segment
pattern names a column and splits series on its own, as color would, but every
series is drawn in one color: the theme's single-series color, or the one
style.pattern.color sets. Use it when texture alone should tell series apart.
Add color to give each series its own hue as well:
color: segment pattern: segment
When color is also set, both must name the same column; one column drives both
the hue and the pattern of a series.
On a heatmap, pattern names the measure the cells are shaded by. With no color,
the cells are drawn in one color (the theme's single-series color, or
style.pattern.color) and the pattern ramp alone encodes the value; the legend shows
the ramp's steps. With color naming the same measure, the cells take the color ramp
as well.
A column of categories takes one pattern per value, from the theme's
pattern_category palette. A numeric column takes a stepped ramp from the
pattern_sequential palette: sparse to dense as the value rises, binned into
equal intervals over the column's range.
Pattern style¶
style.pattern controls how patterns are inked:
pattern: temperature style: pattern: color: "#2b4c7e" ground: tint inverse: true palette: pattern_diverging steps: 7
| Key | Values | Meaning |
|---|---|---|
color |
a color or palette token | The pattern's color. Default is the theme's single-series color. Setting it on a chart with a color: channel is an error: with a channel, each series' pattern takes its hue. |
ground |
background (default), tint, a color, or a color palette name |
What the pattern is drawn on. background is the chart background. tint draws a darker shade of the pattern color on a pale tint of it. A color gives every series that ground. A color palette name (such as category-6-tonal-blue) gives series n the palette's color n as its ground, with the pattern drawn over it; the palette must have at least as many colors as the chart has series. |
inverse |
false (default), true |
Swap the pattern's ink and ground. |
palette |
a pattern palette name or a pattern role | Which patterns to use. By default a discrete column takes pattern_category and a numeric column takes pattern_sequential. A palette's kind must suit the column: a categorical palette for categories, a sequential or diverging palette for numbers. |
steps |
3 to 9 |
Number of ramp steps, overriding the palette's own count. Only for a numeric column; setting it on a category pattern is an error. |
The pattern roles are pattern_category, pattern_sequential, and
pattern_diverging; a theme binds each to a palette in its style.palettes: map.
| Palette | Kind | Notes |
|---|---|---|
pattern-mixed-8 |
categorical | The default: hatch, dots, dashes, hexagons, worms, crosshatch, pebbles, and a pixel dither. |
pattern-mixed-12 |
categorical | Twelve patterns. Its first seven match pattern-mixed-8, so a chart can switch without reshuffling them. The late slots come last because they degrade in skinny marks. |
pattern-regular-8 |
categorical | Regular geometry only, for boards that avoid irregular textures. Slots 5 to 7 (grid and horizontal and vertical stripes) degrade in skinny marks: vertical stripes vanish in narrow vertical bars, horizontal stripes vanish in thin horizontal bars and short stacked segments, and the grid falls back to its surviving direction. |
pattern-dots |
sequential | The default numeric ramp: sparse to dense dots, six steps. |
pattern-hatch |
sequential | A ramp from sparse hatch to dense crosshatch, six steps. |
pattern-hatch-dots |
diverging | Dots on one side of zero, hatch on the other, denser away from the zero step; seven steps. |
A mark too small to show a pattern repeat draws a flat tint with an outline instead.
Where patterned shapes touch (stacked and grouped bars, stacked area bands, pie and donut
wedges), neighbors share one line centered on their edge, with no gap, on every ground:
2 px between wedges and 1.5 px between bars and bands. The line is the pattern's color. With
inverse: true the ink is the ground, so the line is the chart's background color instead.
Channel reference¶
| Channel | Chart types | Value type |
|---|---|---|
color |
All | str (color) |
opacity |
All | float [0, 1] |
stroke.color |
Bar, line, area, arc | str (color) |
stroke.width |
Bar, line, area | float |
pattern |
Bar, area, pie, donut, heatmap | str (column) |
Tables¶
On type: table, the table renderer reads each column's conditional
rules directly at render time. Per-channel color.scale /
background.scale still lower to style.columns[<column>].scale because
scale is a continuous encoding the renderer interpolates per cell.
KPI channels¶
On type: kpi, the card fill is style.background: a color, or
{column, scale} to paint it by the value's position in the scale. Rule-driven
overrides (a mix of background and font color/weight per threshold) go under
style.conditional:, and the body path names the row each rule styles. good
and support.good write the sign rules for the headline and the support line.
Provide explicit min/max in gradient scale for KPIs; auto-domain over a
single row always collapses.
queries: totals: type: values columns: [growth] values: - [0.4] charts: growth_kpi: type: kpi query: totals value: growth style: background: column: growth scale: palette: ["#ffffff", "#3366cc"] min: 0 max: 1 conditional: growth: - lt: 0 background: "#fee2e2" value: font: color: "#991b1b" rows: [growth_kpi]
Precedence¶
chart.<channel> (data-bound) wins over chart.style.<channel> (literal).
Using a data-bound form under chart.style.<channel> is a validation error.
On type: table, a column's conditional rules apply on top of the per-channel
encoding for matching rows, as do a type: kpi chart's style.conditional
rules (a matched rule's background beats the gradient).
A KPI's support row colors below its style.conditional outputs, which
win over everything:
- support value:
style.support.font.color, thenstyle.support.tone, then muted ink - support glyph:
style.support.glyph.font.color, thenstyle.support.tone, thenstyle.support.font.color, then muted ink - headline glyph and affix: their own
font.color, then the headline value's ink
Legend¶
When color is bound to a series column, dbt Charts renders a legend mapping
each distinct value to its swatch. Two style.legend fields tune the legend
itself without touching the color scale:
symbol_limit: caps the number of legend entries shown. Useful for a high-cardinality series that would otherwise overflow the legend area.values: an explicit list pinning which entries appear in the legend and in what order, overriding the default order dbt Charts infers from the color scale's domain. This only reorders/filters the legend itself; it does not filter which rows are plotted on the chart.values: []renders an empty legend; it does not fall back to the default order the way an omittedvalues:does.
Each entry in values can be spelled either the way the legend renders it,
or as the underlying column/measure name: case, -/_/space differences
all resolve to the same entry (net_revenue, Net Revenue, and
net-revenue all select the same series). A dimensionless wide
y: [...] chart's legend text always matches its y-axis title, so
either the raw column name or that display text works there too. When
the chart also authors color: as a dimension the measures cross with,
each entry is a <dimension value> - <measure label> composite instead:
author that composite spelling (the dimension value paired with either
the raw or the display measure name). The bare measure name alone is
ambiguous across dimension values and will not resolve.
An entry that doesn't match anything, or matches more than one domain entry, is dropped and reported with a warning naming what it tried and the real domain. If every authored entry misses, the legend falls back to its full default order instead of rendering empty.
This resolution covers every nominal/ordinal color: field on the
families above, including a wide y: [...] chart and an overlay's
layers: labels. A point_map/bubble_map's legend, a temporal
(date/timestamp) or boolean color: column's legend, and an all-null
color: column (inferred as numeric, the same as any other quantitative
column) are not resolved: values there is used exactly as authored,
with no matching and no diagnostic on a miss. Neither is an overlay
whose base y isn't quantitative: its shared color scale is never
built, so legend.values passes through verbatim there too.
queries:
revenue_by_channel:
columns: [month, channel, revenue]
values:
- ["2026-01", "Organic", 42000]
- ["2026-01", "Paid", 18000]
- ["2026-01", "Referral", 9000]
- ["2026-02", "Organic", 47000]
- ["2026-02", "Paid", 21000]
- ["2026-02", "Referral", 8500]
charts:
channel_revenue:
query: revenue_by_channel
type: bar
title: Revenue by Channel
x: month
y: revenue
color: channel
style:
legend:
values: ["Paid", "Organic", "Referral"] # pin legend order
symbol_limit: 5
rows:
- channel_revenue