Skip to content

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, then style.support.tone, then muted ink
  • support glyph: style.support.glyph.font.color, then style.support.tone, then style.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 omitted values: 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
Revenue by ChannelPaidOrganicReferralJan2026Feb020,00040,000 Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶