Skip to content

Tables and Text

Tables present values directly in rows and columns, making lookup, exact reading, and dense comparison possible; this family includes plain text tables, colored tables, and spark tables. They are most useful when the reader needs exact numbers, many values at once, or a structured reference view rather than a strongly shaped visual pattern.

This page will also cover other data-powered text-like outputs that are not really Vega-Lite charts at all, such as KPI blocks, large single-value callouts, and future narrative or AI-generated summary text. In other words, this family is not just about tables as rows and columns; it is about text-oriented outputs that are driven by data and are often used when exact reading, summarization, or direct communication matters more than visual encoding.

A chart's control surface is the full set of authored properties available on a single chart. In dbt Charts, that surface is primarily top-level chart fields plus a typed style object.

This page is intentionally family-oriented rather than exhaustive. For the implementation-backed source of truth, including table, KPI, spark, and spark_bar property coverage, see the YAML Schema Reference.


Table Charts

Use type: table when exact values, scanning, and dense comparison matter more than mark-based trend reading.

Minimum Required for a Table

dbt Charts field Maps to renderer behavior Allowed values Notes
query table data rows Query name or query reference Supplies the dataset.
type: table table SVG renderer Literal table Selects the table renderer.

Table-Specific Style

Table-specific style fields go directly under style: (for example, style.row_numbers.visible, style.columns). Chart-level style: is typed as TableChartStylePatch; its fields sit at the root of the chart's style: block. Using style.table.* nesting raises a validation error (extra inputs are not permitted).

dbt Charts field Maps to renderer behavior Allowed values Notes
style.columns per-column display config Mapping of column name → config object Styling only: configures labels, formatting, width, alignment, header links, and inline sparks for the columns it names; every column the query returns renders whether or not it is listed, in the query's own order. Hide a column with visible: false; use column_name: {} for a bare column with defaults.
style.hide_underscore_columns hide _-prefixed query columns true (theme default) or false A query column whose name starts with _ is hidden unless it has its own style.columns entry. See Hidden underscore columns.
style.column_defaults table-wide column defaults TableColumnDefaultsConfig object Sets width, align, format, background, and font for all columns; per-column entries override field-by-field.
style.header_overflow header overflow behavior clip, truncate, wrap-two (default), or wrap Controls how long table headers clip, truncate with ellipsis, or wrap. Headers wrap to two lines unless you set this.
style.background chart SVG background wrapper Color value Applies a chart-level background fill behind the rendered table SVG.
style.column_layout.width_similarity_threshold column cluster equalization threshold Float 0.0–1.0 (default 0.8) Auto-width columns whose min/max ratio ≥ this value are snapped to a shared width before budget allocation. 0.8 = within ~20% get equalized; 1.0 = disabled (pure proportional); 0.0 = all auto-columns equal.
style.symbol_mode currency-prefix / magnitude-suffix placement on numeric columns anchors (theme default) or all anchors shows the full formatted value only on the first data row and on summary/total rows, stripping the prefix from plain middle rows; the anchor rows carry the unit so the reader doesn't need it repeated on every line. The magnitude suffix (K/M/B) is never stripped: a missing K changes a value a thousandfold, so every nonzero row keeps its own (see Number Formatting below). all shows the full formatted value (prefix + number + suffix) on every row. A pivot table's measure cells always show the symbol on every cell, since a cross-tab has no single top row; a column format's repeat: anchor still anchors it.

To disable column equalization for a chart that needs strict proportional sizing (for example, a revenue waterfall where the column widths carry meaning) set the threshold to 1.0:

style:
  column_layout:
    width_similarity_threshold: 1.0  # disable equalization; use strict proportional widths

Every built-in theme defaults symbol_mode to anchors: a currency or percent symbol only at the top and bottom of a numeric column. To show the symbol on every row instead, set symbol_mode: all:

style:
  symbol_mode: all  # "$1,234" on every row instead of just the first data row and the total row

Row Presentation (style.row)

The style.row block controls body-row defaults and per-role overrides for summary and total rows. The singular row name avoids confusion with the board-level rows: layout key.

dbt Charts field Maps to renderer behavior Allowed values Notes
style.row.height body row height (px) Number Body row height.
style.row.divider.visible draw row separators true, false Row separators are off by default.
style.row.divider.width row separator width (px) Number Row separator width.
style.row.divider.color row separator color Color value Sets the row separator color; overrides the theme default.
style.row.roles.summary.font.weight summary row font weight "400", "500", "600", "700" Summary-row font weight.
style.row.roles.summary.background summary row fill Color value Fill behind summary rows.
style.row.roles.total.font.weight total row font weight "400", "500", "600", "700" Total-row font weight.
style.row.roles.total.background total row fill Color value Fill behind total rows.
style:
  row:
    height: 15
    divider:
      visible: true
      width: 2
      color: "#D32F2F"
    roles:
      summary:
        font:
          weight: "500"
      total:
        font:
          weight: "700"
        background: "#F5F5F5"

Which rows are summaries and totals is data, so it is named on the chart rather than in style. row_role: is a chart-root field holding the name of a query column; the column's value on each row is value, summary, or total, and the column itself is never drawn. A row_role that names no column of the query is an error. Totals and summaries pin to the bottom when the table is sorted, and stay out of the row numbers and the page count.

queries:
  sales:
    type: values
    columns: [region, revenue, kind]
    values:
      - [West, 812, value]
      - [East, 654, value]
      - [All regions, 1466, total]
charts:
  sales_table:
    query: sales
    type: table
    row_role: kind
    style:
      row:
        roles:
          total:
            font:
              weight: "700"
rows:
  - sales_table

Row Numbers (style.row_numbers)

The style.row_numbers block injects a synthetic leading column that numbers data rows 1, 2, 3, ..., the same presentation as Excel, Google Sheets, and Looker's show_row_numbers. The column is transparent to style.columns (authors don't list it), to a column's conditional rules (no rules target it), and to the data pipeline (it is a chart-layer concern, not a query column).

dbt Charts field Maps to renderer behavior Allowed values Notes
style.row_numbers.visible toggle on/off true or false Default false; off unless set.
style.row_numbers.header column header text String Default "#".
style.row_numbers.align cell text alignment left or right Default right, matching numeric convention.
style:
  row_numbers:
    visible: true   # the one key needed; header "#" and align right are the defaults

Pagination behavior: numbering is continuous across pages. Page 2 of a 100-per-page table starts at row 101; it never resets to 1. The column width sizes against the total row count (not the per-page count), so page 1 and page 5 of a 200-row table have the same row-number column width.

Summary / total rows: the row-number cell is blank on rows tagged as summary or total (via row_role). The sequence counts data rows only, wherever the query places the total, and so does the pager's row range: 214 data rows and a total read 1–20 / 214.

Table Pagination

Tables support client-side row pagination via style.pagination. This controls how many rows are visible per page; it is a presentation concern, distinct from query-level limit which controls how many rows are fetched.

dbt Charts field Maps to renderer behavior Allowed values Notes
style.pagination enables row paging Object Use the object form shown below.
style.pagination.enabled toggle pagination on/off true or false Defaults to true when pagination is present.
style.pagination.page_rows rows per page Positive integer or null Optional; defaults to 20. A ceiling: a page never holds more rows than the tile height fits. null means unlimited: the tile height alone sizes the page.
style.pagination.mode vertical scroll or pager scroll (default) or pages scroll shows page_rows rows at a time and scrolls the rest under a pinned header. pages shows one page of rows at a time instead. Both draw the same pager below the rows. No effect with enabled: false. See Scrolling.

Use the full object form:

style:
  pagination:
    page_rows: 25   # enabled defaults to true once pagination is present

Design note: style.pagination is purely presentational. Use query-level limit when the intent is to fetch fewer rows. The Looker migration exporter maps limit_displayed_rows / num_rows to style.pagination.page_rows, preserving the distinction between data truncation and UI paging.

Scrolling

A table scrolls inside its slot instead of squeezing or growing the board: with the mouse wheel or trackpad (Shift + wheel scrolls sideways), by dragging a scrollbar, by touch, or from the keyboard once the table has focus. The header stays pinned, and so does a total or summary row. A table that scrolls its rows shows page_rows rows and half of the next, so the reader can see there is more. The pager below the body (with the row range, for example 1–10 / 60) jumps to a page and follows the scroll. Set mode: pages for the plain pager that shows one page at a time. A table one or two rows past a page grows to show every row instead.

dbt Charts field Maps to renderer behavior Allowed values Notes
style.column_layout.overflow columns wider than the slot scroll (default) or fit scroll keeps the columns' width and scrolls sideways. fit squeezes them into the slot, the behavior before scrolling existed. A table that fits draws the same under either value.
style.column_layout.freeze leading columns pinned while scrolling sideways Integer ≥ 0 (default 0) The first N columns stay in place; row numbers, when shown, stay with them. Frozen columns wider than half the table, or freeze with overflow: fit, raise ERR-TABLE-FREEZE-INVALID. Has no effect on a table that fits. A hairline marks the frozen edge, and a fade appears there once the table scrolls.
style.pagination.mode vertical scroll or pager scroll (default) or pages See Table Pagination. Past 1000 rows a scroll table falls back to pages and raises WARN-TABLE-SCROLL-ROWS-CAPPED.
style.scrollbar.size scrollbar thickness (px) Number > 0 Theme default 6. A table that scrolls its rows reserves size plus twice inset at its right edge for the vertical bar.
style.scrollbar.inset gap between scrollbar and table edge (px) Number ≥ 0 Theme default 2.
style.scrollbar.thumb_color color of the draggable bar Color value Theme default is a mid-gray chrome color.
style.scrollbar.edge_color hairline between frozen and scrolling columns Color value Theme default is a light chrome gray, kept lighter than the table's black rules.
style.scrollbar.track_color color of the strip behind the bar Color value or null Default null: the bar is drawn alone.

Pin the first column of a wide table and scroll ten rows at a time under a fixed header:

style:
  column_layout:
    freeze: 1        # the first column stays visible while the rest scroll sideways
  pagination:
    page_rows: 10    # ten rows in view; the rest scroll under the header
  scrollbar:
    track_color: "#EEEEEE"

To flip between pages instead of scrolling them:

style:
  pagination:
    mode: pages

To keep the old squeeze-to-fit behavior for one table:

style:
  column_layout:
    overflow: fit

Set the same keys under style.charts.table on the board to apply them to every table; a chart's own style: still wins.

A picture cannot scroll, so dct render --format png and --format pdf, and a board's PNG and PDF downloads, draw every table as overflow: fit, with no frozen columns: the export shows every column, squeezed, rather than only the ones that fit the slot.

Sorting and filtering

On interactive surfaces (dct serve, dbt Charts Platform, the Playground, Streamlit), readers can sort and filter a table in the page. Click a column header to open its menu:

  • The sort items name the order by column type: Sort A → Z and Sort Z → A for text, Sort 1 → 9 and Sort 9 → 1 for numbers, Sort oldest → newest and Sort newest → oldest for dates. Clear sort restores the order the query returned. Empty cells, and values like N/A in a numeric column, always sort last.
  • Filter by date range appears on a date column, one where every non-empty value is a date or timestamp. It is the calendar the board's date range controls use: click a first and a last day, or one day twice for a single day; both ends are included and Clear drops the range. A timestamp falls on the day it shows in the board's time zone, and an empty cell is hidden while a range is set.
  • Filter by values is a checklist with a search box, offered when the column has at most 100 distinct values. Uncheck values to hide their rows; Select all and Clear check or uncheck every value the search shows. Filtering matches the text the cell displays. On a date column it starts folded under the calendar. A date range and the checklist combine: a row shows only if it passes both.

A sorted column shows an arrow in its header, and a filtered column shows a dot. Summary and total rows stay at the bottom, are never sorted, and are hidden while a filter is active, because the query computed them over rows the filter now hides. Paging keeps working over the sorted and filtered rows.

Sorting and filtering act on the rows the query returned, limit included. A table over limit: 200 sorted by name shows those 200 rows in name order; it does not fetch the rows a different sort would have kept. To filter before the limit, add a board variable and use it in the query.

Nothing is saved: a reload, a variable change, or a new render starts from the query's order. Static exports do not sort or filter. A pivot table sorts and filters its rows from any row or pivoted column header; its pivoted columns keep their order. Tables with more than 1,000 rows and tables with subtotal rows between detail rows (only a trailing total or summary run qualifies) are not sortable in the page; they keep paging through the <chart>_page variable.

Conditional Formatting (style.columns.<column>.conditional)

A table restyles a column's cells by value through that column's conditional: list, under style.columns.<column>. The rules test the column's own value and paint the column's own cells, and are evaluated top-to-bottom like spreadsheet rules. This is the canonical mechanism for changing a cell's background, font.color, or font.weight based on a predicate over its value (thresholds, equality, a default catch-all). (style.columns[].background/.font can also resolve per-row from another column's raw value with no predicate involved; see Per-row style from another column below.)

A rule is one predicate plus the cell style it applies: the same background, font and glyph keys a column takes under style.columns.<column>.

Predicate Meaning
gte: <number or date> value is greater than or equal to
gt: <number or date> value is strictly greater than
lte: <number or date> value is less than or equal to
lt: <number or date> value is strictly less than
eq: <value> value equals (string, number or boolean)
ne: <value> value does not equal
between: [<low>, <high>] value is in the range, ends included; two numbers or two dates
in: [<value>, ...] value is one of the listed values
is_null: <true or false> value is null (true) or not null (false)
default: true catch-all; place last

A <number> or between bound can be an aggregate of the column, computed over every row: min(), max(), avg(), median() or percentile(<0-100>). eq and ne take min() or max(). A pivot table's rules take no aggregate.

A rule names exactly one predicate. What it can set is the part of a column's style that can differ from one row to the next: background, font.{color, weight, style, decoration}, glyph (a character prepended to the cell value), glyph_color, and the rule-only tone. Anything else, such as align or pagination, is rejected. conditional belongs to one column of one chart: it is refused under style.charts.table, at the theme or board level, and in column_defaults. A column with visible: false cannot take rules, since nothing would paint; test a hidden column with a row rule instead.

Rules are evaluated per row, per column, in list order. Every matching rule other than default: true contributes its style keys, and a later match wins over an earlier one for a given key. List the more specific rule last: with gte: 0.9 first and gte: 0.98 after it, a value of 0.99 takes the second rule's background and keeps the first rule's bold weight. A default: true rule applies only when no other rule matched.

charts:
  cf_revenue_table:
    type: table
    query: product_category_revenue
    style:
      columns:
        revenue:
          conditional:
            - gte: 30000
              background: "#e0f2fe"
            - gte: 50000
              background: "#dcfce7"
              font:
                color: "#166534"
                weight: "bold"
            - default: true
              background: "#fef3c7"
        category:
          conditional:
            - eq: Electronics
              background: "#ede9fe"
            - eq: Accessories
              background: "#cffafe"
            - default: true
              background: "#f4f4f5"

Glyph tone

A rule that sets glyph can color it either way: glyph_color takes a raw color, or tone names a semantic role (positive, negative, warning, info) that resolves through the theme's tone palette. Prefer tone; it adapts across themes, and it is the same vocabulary KPI cards use. Both need a glyph, from the rule or from the column's glyph; an explicit glyph_color wins if you set both.

charts:
  tone_revenue_table:
    type: table
    query: product_category_revenue
    style:
      columns:
        revenue:
          conditional:
            - gte: 50000
              glyph: "▲"
              tone: positive
            - lt: 30000
              glyph: "▼"
              tone: negative
            - default: true
              glyph: "●"
              tone: info

tone colors the glyph only; it does not repaint the cell's text or background. Use font.color and background for those, or scale: for a continuous gradient.

Why on the column: the rules sit beside the format, glyph and label of the column they paint, so one column's look reads in one place. A rule always tests the cell it paints; to color one column by another column's value, use per-row style from another column.

For value-driven gradients (continuous color across a numeric range), see the scale: config, separate from rules. Both compose under style.

Row Rules (style.row.conditional)

A column's conditional: list tests its own value and paints its own cells. To restyle a whole row, or another cell in it, from any column's value, use style.row.conditional. It is keyed by the column the rules test, like a KPI's style.conditional, and the tested column can be hidden.

style:
  row:
    conditional:
      status:
        - eq: churned
          background: dbt-grays.2
          columns:
            name:
              font:
                decoration: line-through
      profit:
        - lt: 0
          columns:
            name:
              background: positive.bg
      _at_risk:
        - eq: true
          background: warning.bg

A rule is one predicate (the same ten as above) plus what it paints:

  • background and font.{color, weight, style, decoration} paint every visible cell of the matching row.
  • columns.<column> paints one cell of the row with background, font, glyph, glyph_color and tone. The target must be a visible query column. Glyphs exist only per cell, so they are not accepted at the row level.

Rules evaluate per row in list order: every matching rule applies, a later match wins per key, and default: true applies only when no other rule in that column's list matched. Two tested columns cannot set the same property of the same target; the table refuses it, naming both columns. Summary and total rows (row_role) are evaluated like any other row, layered over style.row.roles; test the role column in a rule if a total should be skipped.

On one cell, later layers win: column_defaults, then style.columns.<column>, then row rules, then scale, then the column's own conditional rules. A red negative cell stays red inside a gray churned row.

A condition that needs several columns or comparisons (profit < 0 and region = 'EU', actual < target) belongs in SQL as an underscore column, hidden by default (see Hidden underscore columns), that a row rule tests:

select *, (actual < target) as _below_target from regions

style.row.conditional is chart-local like style.columns.<column>.conditional: it is refused under style.charts.table. It is not supported on pivot tables or with transpose.

Table Column Config

style.column_defaults sets shared defaults applied to every rendered column, listed in style.columns or not. Per-column entries override field-by-field:

style:
  column_defaults:
    width: 36
    align: center
  columns:
    c1: {}
    c2: {}
    c3:
      background: "#fee2e2"  # overrides background; width/align come from defaults

When all columns share the same presentation (width, alignment), you only write the defaults once and use empty config objects for columns that only inherit defaults.

Set style.header.visible: false to hide the header row; no header height is reserved:

style:
  header:
    visible: false

style.columns is styling only: it configures the columns it names and never selects which columns render, or in what order.

Column order comes from the query's SELECT list (or the pivot spec's, when rows:/columns:/values: are authored); reordering style.columns keys has no effect on where a column renders. To move a column, reorder the SELECT list. This is the single most common table-authoring mistake: style.columns is where every other per-column knob lives (label, format, align, visible), so reordering its keys looks like the obvious way to reorder columns, and it silently does nothing. (Exception: a zero-row result has no query order to fall back on, so its empty-state headers render in style.columns' own key order instead.)

Every column the query returns is displayed; naming a subset in style.columns styles that subset and nothing else. To remove a column from the render, set visible: false on it: the column disappears entirely and the remaining columns close up around it; its values stay available to link: templates and column-ID style references. Columns that only exist to feed styling (see Per-row style from another column) are hidden automatically, unless they have their own style.columns entry, which is a display signal and shows the column. Keep display-data selection in the query's SELECT; a column the table should never see shouldn't be queried at all unless a link or style input needs it.

Each style.columns.<column_name> entry can set:

  • visible: false hides the column while keeping its per-row values available to link: templates and style-input references; defaults to true
  • label: header text; defaults to the humanized column name. label: "" prints a blank header, handy over an inline spark column.
  • format
  • width: hard pin to an exact pixel value or percentage (for example, 200 or "20%"). Cannot be combined with max_width:.
  • max_width: cap on auto-sized text columns (see below). Cannot be combined with width:.
  • align: left, center, or right. Numeric columns set their digits on a shared decimal lane by default; left anchors each value's digits at the cell's left edge instead, with no decimal alignment between rows, and moves the header with them.
  • header_link
  • link: cell-level hyperlink; supports a static URL, a column ID (uses per-row value), or a template with {{ column_id }} placeholders. A column formatted email or url (see text formats) links without one; an authored link:, a foreign-key drill and a filter link each win over it, and empty cells stay plain text
  • spark: draw a miniature chart in the cell instead of the value's text (see Inline Spark Columns)
  • swatch: render the cell as a small color chip instead of text (see below)
  • list: the cell holds a list of values, drawn one per line and opened per row (see List Columns)
  • background: a hex color (or transparent/none), or a column ID (uses per-row value; see below)
  • font: font.color and font.weight accept a column ID the same way background does

style.column_defaults supports width, align, format, background, and font. Data-dependent fields (link, header_link, spark, swatch, list, scale, glyph) are not available as defaults. column_defaults.font.color is the table's cell text color.

Spanners

spanners: draws a label over a run of adjacent columns, so a shared category is written once instead of in every column label. It adds one header row above the column headers; the label is centered over exactly the columns it names, with a rule beneath them. Columns that no spanner names (and the row-number column) get a blank, unruled cell in that row.

queries:
  by_region:
    type: values
    columns: [region, q1_revenue, q2_revenue, q1_heads, q2_heads]
    values:
      - [West, 812, 904, 31, 34]
      - [East, 654, 701, 24, 25]
charts:
  regional:
    query: by_region
    type: table
    spanners:
      - label: Revenue
        columns:
          - q1_revenue
          - q2_revenue
      - label: Headcount
        columns:
          - q1_heads
          - q2_heads
    style:
      columns:
        q1_revenue:
          label: Q1
        q2_revenue:
          label: Q2
        q1_heads:
          label: Q1
        q2_heads:
          label: Q2
rows:
  - regional
  • spanners is a chart-root list; each entry takes label and columns (at least one column name).
  • Spanners never reorder columns. The columns of one spanner must be adjacent in the query's SELECT order; reorder the query to group them.
  • A column belongs to at most one spanner, and every name must be a query column. Any violation is an error that names the offending columns.
  • A column hidden with style.columns.<column>.visible: false leaves its spanner and the span narrows; a spanner whose columns are all hidden is dropped. Adjacency is judged on the columns that remain visible.
  • Spanners are single-level and use the header font. They cannot be combined with the pivot channels (rows:, columns:, values:), which draw their own spanners from the pivot dimensions.

Per-row style from another column

background, font.color, and font.weight resolve column-ID-first, the same way link does above: if the configured value matches one of the query's column names, the cell uses that row's value in the named column instead of treating the string as a literal. This lets a helper column computed by the query drive per-row cell styling directly, with no when: predicate. A column consumed this way is hidden from the render automatically, its values are paint, not display data, with no visible: authoring needed. Two exceptions: link: source columns are not auto-hidden (hide those explicitly with visible: false), and a consumed column with its own style.columns entry renders; an explicit entry is a display signal.

style:
  columns:
    account:
      background: status_color   # per-row: uses each row's status_color value, not the literal string "status_color"

If the configured value doesn't match a column name, it's used as a literal: a hex string (transparent/none also accepted) for background, or "bold" / "400" … "700" for font.weight. Neither field raises on an unrecognized value: an unresolvable color (a mistyped column name, or an unsupported literal like a CSS color name) silently paints no background instead, an unrecognized font.color silently leaves the cell's default ink color, and an unrecognized weight silently falls back to the default text weight; check the rendered output rather than relying on a compile-time error. The same applies to a NULL or empty helper-column value: the cell renders unstyled, with no error.

Precedence: a matching conditional rule on the same column overrides the column-ID value; with no match, the column-ID value stands. Don't combine column-ID background/font.color with scale: on the same column: scale: reads the unresolved configured string as its own base value, so a column-ID reference (not a real color) fails scale:'s color check and silently discards the background/color for every row, not just unmatched ones.

This is a narrower mechanism than a column's conditional rules (above): it always uses the raw value of another column, with no predicate. Reach for conditional when the styling decision depends on a threshold or comparison; reach for this when the query already emits the exact style value per row.

Hidden underscore columns

A query column whose name starts with an underscore is hidden from the table. Use it for values the table needs but the reader doesn't: a flag a rule tests, an ID a link: reads, or pipeline metadata such as _fivetran_synced. A hidden column's values still feed links and per-row styling.

A condition too rich for one rule (several columns, or more than one comparison) belongs in SQL as an underscore column:

select
  name,
  arr,
  case when profit < 0 and region = 'EU' then 'bold' else '400' end as _weight
from accounts
style:
  columns:
    name:
      font:
        weight: _weight   # reads each row's _weight; the column itself stays hidden

A _ column with its own style.columns entry renders. To show every _ column on one table, turn the setting off:

style:
  hide_underscore_columns: false

To turn it off for a whole board, or for the whole project in charts/meta.yml, set it under style.charts.table:

style:
  charts:
    table:
      hide_underscore_columns: false

Color Swatch Columns

Set swatch: true on a column whose cell values are CSS color strings (for example, "#3164a3") to render each cell as a small rounded color square instead of text. This is useful for series-keyed tables, a "Series" or "Color" column where each row's swatch matches that row's color elsewhere on the board:

style:
  columns:
    kind:
      label: Color
      swatch: true

The column's underlying data must already be CSS color strings; swatch only changes how the cell renders, not the query.

List Columns

Set list: true on a column whose cells hold lists, such as a query that returns one row per group with array_agg(owner) as owners. Each value prints on its own line:

style:
  columns:
    owners:
      list: true

On a live board (dct serve, an HTML export, or dbtCharts.com), a row whose lists hold more than one value starts shut and shows a chevron in a narrow gutter left of the first column; clicking the chevron opens that row in place. The table grows to fit, the pager stays under the last row, and anything below the table on the board moves down. A list with a single value always shows it. In a table that scrolls, opening a row lengthens the scroll instead of the board. A static export (SVG, PNG, or PDF) draws every list open, so no values are hidden.

The query owns the grouping: list only changes how a list cell renders, and the column must hold arrays (a column of text is an error, never split into a list). Each value is plain text, so format, spark, and swatch are not available on a list column. Sorting and filtering still apply to whole rows.

Inline Spark Columns

Set spark: on a column to draw a miniature chart inside each cell instead of the value's text. The shorthand is a variant name; the full form is a block with type: plus options:

style:
  columns:
    monthly_trend:
      spark: line
    quota_pct:
      spark:
        type: bar-normalize
        max: 100
        color: "#22c55e"

The query delivers each spark's data, one cell per row, already shaped for the variant: line, area, and columns read an array of numbers; bar, bar-normalize, and column read a single number. On a single-number variant, a null cell renders blank and a non-numeric cell falls back to its text, so one spark config can cover a table that mixes text and numeric rows. A summary or total row (via row_role) draws no spark and prints its value instead, since a total's bar would run past every data row's scale.

spark.type Draws Cell value Scaling
line mini line chart array the array's own range
area filled mini line chart array the array's own range
columns one vertical bar per array element array the array's own range
bar one horizontal bar, no background track number width relative to the column's largest absolute value, or to max: when set
bar-normalize one horizontal bar over a background track number width as a share of max: (theme default when unset); reads as "% of ceiling"
column one narrow vertical bar, bottom-anchored, no track number height as a share of max: (theme default when unset); bar-normalize turned upright

Variant names mirror chart.type: a full-size vertical bar chart is type: bar, while the in-cell mark that draws many vertical bars is columns (plural, because each cell renders several). Use bar for magnitude and bar-normalize for percentages: draw a track only when there is a meaningful 100%.

dbt Charts field Maps to renderer behavior Allowed values Notes
spark.type variant line, area, bar, bar-normalize, column, columns Default line.
spark.color mark color CSS color Defaults to the theme's spark color; bar, bar-normalize, and column default to the theme's spark bar color.
spark.width mark width in pixels Positive integer bar and bar-normalize size their column to fit it, defaulting to the theme's spark.bar.width (80px); other variants default to the cell width (column to the theme's narrow column width) and are capped to the cell.
spark.height mark height in pixels Positive integer Defaults from the row height; capped to it.
spark.last_visible dot on the last point true or false line and area.
spark.min_max_visible dots on the min and max points true or false line only.
spark.fill_opacity fill opacity 0–1 area only.
spark.max scaling ceiling Number bar-normalize and column clamp the value to it; bar uses it in place of the column's data max.
spark.thresholds fill color by value Mapping of number → CSS color bar, bar-normalize, column. The bar takes the color of the highest threshold its value reaches; below the lowest threshold it keeps the theme's spark bar color. Ignored when color: is set.
spark.background track color behind the bar CSS color bar draws a track only when it is set; bar-normalize always draws one, defaulting to the theme's spark.bar.background.
spark.border_radius corner radius of the bar and track, in pixels Number bar, bar-normalize, column.
spark.value.visible draw the cell's value in its own lane beside the mark true or false bar, bar-normalize, column; default false. Any spark.value on line, area, or columns is an error.
spark.value.position which side of the mark the value lane sits on left or right Defaults to the theme's charts.table.spark.value.position (right).
spark.value.gap gap between the value and the mark, in pixels Number, 0 or more Defaults to the theme's charts.table.spark.value.gap (6).
spark.negative_color paint negative values with the theme's tones.negative color true or false bar, column, columns; default false. No effect on bar-normalize or on a column with no negative values.
style:
  columns:
    quota_pct:
      label: Quota
      spark:
        type: bar-normalize
        max: 100
        thresholds:
          0: "#ef4444"
          70: "#f59e0b"
          85: "#22c55e"
    monthly_trend:
      label: 6-Month Trend
      spark:
        type: line
        last_visible: true

A spark bar draws no value inside the bar; a nonzero value always draws at least 1px, so it never vanishes beside the column's largest value. To show the number beside it, set spark.value; the cell splits into a value lane and a spark lane under one header, and the lanes never overlap. The value sits right of the mark by default; position: left puts it first:

style:
  columns:
    revenue:
      format: currency_whole
      spark:
        type: bar
        value:
          visible: true

The value takes the column's format, align, and font, and its lane is as wide as the widest formatted value in the column. A summary or total row prints its value in the value lane and leaves the spark lane blank; a null cell leaves both blank. spark.width sets the mark's width (bar and bar-normalize default to the theme's spark.bar.width), and a pinned column width too narrow for it is an error. The theme's charts.table.spark.value sets the default position and gap for every column; a column's own spark.value.position or spark.value.gap overrides it.

Negative values. bar, column, and columns grow from a midline once a negative value is present: positives grow right or up, negatives grow left or down. For bar and column that decision is made per table column, so every row shares one anchor; columns decides from its own array. A column with no negatives keeps the full-width or full-height layout. bar-normalize never splits: its track is a fixed "% of max" ruler, so negative values clamp to zero.

Preparing data. The query owns the series: aggregate it in SQL with ARRAY_AGG(value ORDER BY month) (DuckDB, PostgreSQL, BigQuery) or ARRAY_AGG(value) WITHIN GROUP (ORDER BY month) (Snowflake), sorted chronologically for time series. Keep arrays to roughly 10–30 points; more turns the spark to mud. For a distribution, pre-bin in the query and render the bucket counts as columns; binning belongs to the query, not the render.

Auto-sizing: compact vs text columns

The table auto-sizer classifies each column as compact or text based on its measured content demand:

  • Compact columns (demand ≤ 220px, or spark columns) are pinned to their measured demand. Short enums, numbers, dates, and short strings are compact by default.
  • Text columns (demand > 220px) compete proportionally for the remaining budget after compact columns are pinned.

This means a freeform notes or description column no longer squashes every compact column down to unreadably narrow widths. The compact columns keep their natural size; the text column gets whatever is left.

When the board has no width, the measured width sets the board's width, up to the 1200px default. A table that needs more than the available width first wraps its long headers onto two lines and narrows its text columns to 220px (or their longest word, if wider). If it still does not fit, it scrolls sideways inside its slot by default: compact columns keep the width their values and wrapped headers need, and the columns past the slot's edge are a scroll away (see Scrolling). Set style.column_layout.overflow: fit to squeeze the table into its slot instead: headers wrap, cell text is cut with an ellipsis, and WARN-TABLE-HEADER-EXTRA-WRAP, WARN-TABLE-CONTENT-TALLER-THAN-WIDE or WARN-TABLE-TEXT-TRUNCATED names the column that suffers. Either way, set style.frame.width on the board to give the columns room, give a column a wider style.columns.<column>.width, or set style.preferred_width on the table to pin its width. Tables inside cols: still split the row equally; only a table alone in a row, or in rows:, sets the board's width.

On a live board or an HTML export, hover a cut cell to read its full value in a card below it; click the card to keep it open so you can select and copy the text.

max_width:: capping a text column

Use max_width: on a text column to prevent it from growing beyond a ceiling even when there is spare budget:

style:
  columns:
    csm_name: {}
    account: {}
    arr:
      format: "$,.0f"
    next_steps:
      max_width: 400   # cap the freeform text column; compact columns absorb the remainder

max_width: accepts an integer (pixels) or a CSS-style percentage string ("30%"). It is mutually exclusive with width:; setting both raises a validation error at compile time.

When a text column is capped below its natural budget share, the leftover budget is redistributed to the compact columns proportionally, so the table always fills its tile.

Number Formatting

Numeric columns with no explicit format: are formatted at render time using the engine-predefined number format, so large numbers read compactly instead of at full precision. number uses .3~s (three significant figures with an SI magnitude suffix and trailing-zero trim), which renders 452342060.87 as 452M, 20640228.74 as 20.6M, and a fraction like 0.671 as 0.67 (never an SI milli suffix).

When a column's values share one common magnitude (most rows land in the millions, say) the column prints every number at that scale: each row keeps its own capital-letter suffix (212 K, 188 K), hung past the digit edge so the digits stay aligned, and a zero prints bare. Only the currency or percent symbol anchors on the top and summary rows. A chart axis differs: its ticks read as one evenly spaced sequence, so it states the magnitude once on one tick, while a table cell is read alone and must carry its own. A column whose values span very different magnitudes, or that doesn't compact at all, keeps today's per-row formatting.

To show a column at full precision, or in any other style, set format: on that column entry with a d3 numeric spec (or a predefined name such as number_full for plain comma-grouped decimals):

style:
  columns:
    arr:
      format: "$,.0f"   # "$452,342,061"; explicit format overrides the SI default
    order_id:
      format: number_full   # predefined name; plain comma-grouped decimals

An explicit column format: always wins over the default. Assigning a temporal format (a predefined time spec such as time_short, or an explicit strftime string such as "%b %Y") to a numeric column raises an error at render time; this is the reverse of the date-column check below. A date-like value delivered as a string (a bare year like "2024", for example, a mixed date column with a year-only outlier row) is exempt: it renders as-is rather than raising, the same as any other date-like cell.

dct render --format text previews table cells through each column's format, so the formatted value shows there.

Date and Datetime Formatting

Date and datetime values from the warehouse (DATE, TIMESTAMP, TIMESTAMPTZ columns) are formatted at render time using the engine-predefined date_short format; no SQL-side strftime is required. date_short renders 2024-05-19 as 19 May 2024.

To override the format for a specific column, set format: on that column entry using a strftime-style spec (containing a %-prefixed directive such as %B or %W, anywhere in the string):

style:
  columns:
    event_date:
      label: "Event Date"
      format: "%B %d, %Y"   # "May 19, 2024"

Assigning a non-strftime format spec (such as a d3 numeric format like ",.0f") to a date column raises an error at render time; use a strftime spec or omit format: to use the predefined date_short format.

Date columns are right-aligned and excluded from text-wrap layout automatically. A time-zone-aware datetime prints in the board's regional.time_zone (UTC by default), and %Z/%z name that zone; a naive datetime prints as written. The server's local time zone never applies.


KPI Charts

Use type: kpi when the output is fundamentally one important value rather than a plotted series.

Minimum Required for a KPI

dbt Charts field Maps to renderer behavior Allowed values Notes
query KPI data row Query name or query reference Supplies the dataset.
type: kpi KPI renderer Literal kpi Selects the KPI renderer.
value KPI value binding Column reference (string column name) Chooses the value to display.

style.value.format is especially important for KPIs because it controls how that single value is rendered. Content (value, label, glyph, support) sits at the chart root; layout and typography (style.variant, style.support.format, style.support.tone, and each slot's font) sit under style:.


Callout Charts

Use type: callout for a bordered message card inside a dashboard tile. Callouts do not run queries; they are static content with semantic coloring driven by style.tone:.

Runtime chart failures (query errors, data-shape mismatches, render failures) also render as callout cards with explicit tone: negative, using the same renderer and style.charts.callout structure defaults.

Minimum Required for a Callout

dbt Charts field Maps to renderer behavior Allowed values Notes
type: callout Callout renderer Literal callout Selects the callout renderer.
message Body text String Required. Wraps inside the tile width.
title Heading String Optional heading above message.
style.tone Palette role info, positive, negative, warning Optional. Defaults to info.
charts:
  migration_warning:
    type: callout
    title: Migration warning
    message: >
      Two tiles could not be migrated automatically. Review the source
      dashboard before publishing.
    style:
      tone: warning

rows:
  - migration_warning

Theme defaults live under style.charts.callout (padding, border, title/message typography). Per-chart style.tone: selects which palette role supplies background, border, and text colors (info.*, positive.*, negative.*, or warning.*).


Spark Bar Charts

type: spark_bar is a compact ranked text-plus-bar chart used by inspector-style summaries. For authored dashboards, prefer a table with an inline spark column (spark.type: bar or spark.type: bar-normalize) when you need custom column order, formatting, row styling, or conditional formatting.

When you do use type: spark_bar, the bars run horizontally, so the axes are the reverse of a vertical chart: x is the numeric column whose magnitude sets each bar's length, and y is the label column naming each bar. A non-numeric x is an error. label: and value: are not accepted on spark_bar charts.

With only nonnegative values, every bar grows from the track's left edge. If a visible row has a negative value, all visible rows share a midpoint: negative bars grow left, positive bars grow right, and widths scale to the largest absolute finite visible value. Non-finite values do not draw a fill.

charts:
  owners_ranked:
    type: spark_bar
    query: owner_counts
    x: objects
    y: owner

Spark-Bar Style

dbt Charts field Maps to renderer behavior Allowed values Notes
style.max_bars row cap Integer Maximum number of visible rows before truncation.
style.spark_bar.label.visible left label visibility true or false Set false to hide labels beside the bars (default: true).
style.spark_bar.count.visible right count visibility true or false Set false to hide right-side numeric counts (default: true).
style.spark_bar.bar.height row/bar height Integer Controls compactness of the display.
style.spark_bar.bar.color bar fill color Color value Spark-bar paint surface.
style.spark_bar.bar.background bar track color Color value Spark-bar background/track paint surface.