Styling¶

Control the visual appearance of your dashboard globally or per-chart.

For the implementation-backed inventory of single-chart properties, see the YAML Schema Reference. This page explains how that chart property surface relates to reusable themes and style presets.

For the current design-direction note behind dbt Charts's neutral frame colors, including why the product is exploring near-black ink and an off-white app canvas, see Tonal Foundations.

For the dbt Charts-specific chart palette direction, including the full catalog of shipped palettes with visible swatch previews, see Palettes.

Themes¶

A theme paints the whole board: typography, canvas, palette, and every axis, rule, and table row. Five ship with dbt Charts, you select one with a single line, and you build a custom one by extending it.

title: "Sales Dashboard"
theme: neon

rows:
  - revenue_chart

See Themes for all five side by side, what a theme owns versus what a style preset or a chart owns, and how to build a custom theme. This page covers the style: surface a theme paints, and the per-board and per-chart overrides that cascade on top of it.

Title and header overflow¶

Title overflow is a style-owned scaffold behavior. Use style.title.overflow to choose between clip, truncate, wrap-two, and wrap. The default is wrap-two. clip hard-cuts text, truncate adds an ellipsis, wrap-two wraps to two lines and ellipsizes the second line when needed, and wrap fully wraps. The same setting applies to Vega-Lite, table, and KPI chart titles.

For tables, header labels wrap to two lines by default (the theme's charts.table.header.overflow); they do not follow the chart title's overflow mode. Override that with style.header_overflow for the whole table or style.columns[].header_overflow for a specific column.

Styling every chart's title¶

style.title styles the board's own heading (and, by default, feeds every chart title too). Use style.charts.title to style chart titles specifically, apart from the board heading:

style:
  title:
    font:
      color: "#111111"   # Board heading, and chart titles unless charts.title sets color
  charts:
    title:
      font:
        color: "#4b5563"   # Every chart's own title

Any field you don't set under style.charts.title falls back to style.title, which falls back to the theme: you never need to repeat the full set of title fields (font, sizes, position, overflow, and so on) to override just one. Precedence, low to high: style.title < style.charts.title < style.charts.<family>.title < a chart's own style.title (set on that one chart).

Vega-Lite Config Overrides¶

vega.config in dbt_charts.yml lets you set project-wide Vega-Lite config defaults. dbt Charts uses a closed contract for supported keys; see VegaLiteConfig in the source.

# dbt_charts.yml
vega:
  config:
    header:
      labelFontSize: 12
      titleFontSize: 13

defaults/themes/clarity.yaml ships with dbt Charts's default chart house style; the engine maps it to a Vega-Lite config via style_to_vega_lite() at render time.

Global Styling¶

Set styling options for the entire dashboard using style: at the board root. The most commonly authored board-level style keys are:

style:
  background: "#f5f5f5"    # Working-surface background color
  font:
    family: "Inter"        # Font family name
    emoji: monochrome      # Emoji rendering mode
  formats:
    revenue: "$,.0f"       # Custom project-specific format alias
  charts:
    axis:
      grid:
        visible: true      # Chart-level axis grid default

For the full inventory of board-level style: keys, see the YAML Schema Reference. The top-level style: block is typed as StylePatch; all fields are optional, and they cascade on top of the selected theme. Commonly used top-level keys include background, font, formats, palettes, roles, charts, layout, variables, frame, title, text, border, accent, and muted.

Properties like palette, axis, legend, backgrounds, and css (which appeared in older examples) are not valid at the board style: root.

Style Options¶

background: Working-surface background color (hex, rgb, name, or "transparent")
font.family: Font family name
font.emoji: Emoji rendering mode (monochrome, system-default, disabled)
formats: Format alias map (see Format names and aliases)
charts.*: Chart-type style tree: grid, legends, palettes per chart (see Chart-Level Styling)

palettes: (role name → palette file name, for example, category: editorial-10) is authorable at the board level (not on chart-local style:, which rejects it) and still rebinds single-color role tokens (category[2], chrome.ink) wherever one is authored: a board's palettes: merges into the cascade that those tokens resolve against.

That token rebinding is a separate mechanism from palette roles (palette: category instead of palette: editorial-10), which are a built-in-theme-authoring feature only. Substituting a role for the palette file it names happens once, while one of the shipped themes (clarity, neon, paper, stark, vivid) loads. A board's own palettes: does not extend that substitution to the board's palette:/single_series_palette:/gradient palette: fields; nor does a chart's, nor a custom theme board's. Outside a built-in theme's own YAML, those fields must always name a shipped palette (see Color Palettes), never a role.

Data-freshness stamp¶

dbt Charts stamps how fresh the data is (Data as of 09:44 UTC on 30 Jul 2026) in the lower-left footer by default, on the same baseline as the footer attribution. The value is the query time for a fresh render, or the write time of the oldest cached query when results are served from cache, so the board never reads as fresher than it is. It is always shown in UTC, because a static export cannot know the viewer's timezone.

Use style.timestamp.position to move it between the footer baseline and the top row, style.timestamp.align to choose the left or right edge, and style.timestamp.format to change the text, a strftime string that carries the whole line, label included. The default is position: footer and align: left.

style:
  timestamp:
    position: top
    align: right

A custom format that prints a clock time must show its zone; include %Z (or a literal UTC). The value is UTC, and an unlabeled clock would be misread as local time, so dbt Charts rejects a zone-less clock format at compile. A date-only caption needs no zone.

When the timestamp is right-aligned on the footer baseline, dbt Charts keeps the footer attribution on the far right and shifts the timestamp left so the two strings do not overlap. If the footer is hidden, a footer-right timestamp uses the right page edge.

Markdown text styling¶

Markdown prose in a text: block (body copy, inline `code` and fenced code blocks, and > blockquotes) is painted from the theme, so it tracks the active theme and accent automatically. Body text uses style.text.font; headings use style.title.font; links use style.accent. Inline code, fenced code, and blockquotes have their own box style groups under style.text, with the same font / background / border shape used by chart cards and callouts:

style:
  text:
    code:                 # inline + fenced code
      font:
        family: "ui-monospace, SFMono-Regular, Menlo, monospace"
        color: "#222222"
      background: "#f3f4f6"   # code surface fill
      border:
        color: "#e5e7eb"      # code box border
        width: 1
        radius: 4             # rounded code chips / blocks
    blockquote:           # > blockquote
      font:
        color: "#5f6b7a"      # muted quote text
        style: italic
      background: "#f9fafb"   # blockquote surface fill
      border:
        color: "#3b82f6"      # left rule (the theme accent by default)
        width: 3
        radius: 0
    rule:                 # `---` rules and markdown-table gridlines
      color: "#e0e0e0"

style.text.rule.color is the one knob for both horizontal rules (---) and the gridlines of a markdown table written inside a text: block. It does not affect type: table charts; those draw their lines from style.charts.table.header.rule and style.charts.table.row.rule.

font accepts the full font overlay (family, color, size, weight, style, decoration, case); border is the standard width / color / radius group. Every key is optional in a board style:; set just the leaf you want to change (for example style.text.code.background to recolor code chips for one dashboard). The built-in neon theme ships darker code/blockquote surfaces; custom themes set these in theme YAML so all dashboards inherit them.

The font overlay is fully honored for code and blockquote prose: family, color, size, weight, style (italic), and decoration (underline / line-through) all render. case supports upper and lower; the richer transforms (title, sentence, slug, camel) are rejected on markdown prose rather than silently ignored.

Border & Corner Styling¶

Most border: groups in the theme (the text.code / text.blockquote boxes above, and callout cards) accept the full width / color / radius group (plus the optional dash_array / line_cap / dash_offset fields). A few interior slots render corner rounding only: their renderer never draws a stroke, so width and color would validate but do nothing. Those slots accept radius alone and reject width / color / dash_array:

style.variables.input.border: the variable-strip input controls
style.charts.spark_bar.border: the spark_bar chart's outer frame
style.charts.table.spark.columns.border: inline spark.type: columns bars
style.charts.table.spark.bar.border: inline spark.type: bar cells

title: "Top regions"

queries:
  regions:
    type: values
    columns: [region, revenue]
    values:
      - [West, 812000]
      - [East, 654000]
      - [Central, 431000]
      - [South, 298000]

charts:
  region_ranking:
    query: regions
    type: spark_bar
    x: revenue
    y: region

style:
  charts:
    spark_bar:
      border:
        radius: 8

rows:
  - region_ranking

▶

A slot that does draw a stroke keeps the full group. style.text.code.border paints the box around a fenced code block, so all three fields land on the rendered rect: width as the stroke width, color as the stroke, radius as the corner rounding:

title: "Reading a board file"

style:
  frame:
    width: 700
  text:
    code:
      border:
        width: 2
        color: "#9aa4b2"
        radius: 6

rows:
  - text: |
      Every board is a YAML file. A chart names its query, its type, and the
      columns bound to each channel:

          charts:
            region_ranking:
              query: regions
              type: spark_bar
              x: revenue
              y: region

▶

Emoji handling¶

Themes control how emoji codepoints render via style.font.emoji. This field is required; the theme YAML must set it explicitly (no in-code default). The base theme cascade sets emoji: monochrome; all built-in themes inherit this via extends: unless they override it.

Value	HTML surfaces	SVG / PNG via vl-convert	PDF via ReportLab
`monochrome` (default)	Bundled Noto Emoji for the curated set, monochrome; anything else falls to the OS font	Bundled Noto Emoji for the curated set; anything else is a missing glyph	Bundled Noto Emoji on single-emoji runs; mixed-text emoji still gapped
`system-default`	OS color emoji wins (Apple Color, Segoe UI Emoji, Noto Color Emoji)	No emoji font registered; emoji codepoints render as missing glyphs	Missing glyphs
`disabled`	OS color emoji wins (no dbt Charts emoji wiring)	Missing glyphs; no `@font-face` partial shipped	Missing glyphs

# Default: dbt Charts's calm monochrome, same glyphs everywhere
style:
  font:
    emoji: monochrome

# Let the browser pick OS-native color emoji (HTML-only; SVG/PNG degrade)
style:
  font:
    emoji: system-default

# No dbt Charts emoji wiring at all
style:
  font:
    emoji: disabled

Note: system-default and disabled intentionally degrade on SVG/PNG/PDF surfaces; there is no OS fallback on those renderers. monochrome is the mode that carries emoji across surfaces, but only for the codepoints it bundles.

The bundled font covers a curated set of chart-relevant emoji (status marks, trend arrows, time, money, ops, org and geo, marks, documents, smileys, and weather), not the full emoji repertoire. An emoji outside that set falls to the OS font in a browser and is a missing glyph in SVG, PNG, and PDF. Two further limits worth knowing:

A codepoint spelled with the emoji variation selector (U+FE0F), the form most emoji pickers emit, is painted by the OS in a browser even when the bundled font carries it, because that selector requests emoji presentation and browsers answer it with a color font.
Text width is measured against the bundled font, so an emoji outside the set is measured as a narrow placeholder and painted at full width. Expect wrapping to be off around it.

If an emoji you need isn't covered, prefer a word or a chart glyph over relying on the fallback.

CSS Scope & Limitations¶

The style.css file styles the Dashboard Shell (HTML), but has limitations regarding internal Chart elements (SVG).

What CSS Can Style (HTML)¶

Layout: Rows, columns, grids, margins.
Typography: Section titles, markdown text, KPI cards, headers.
Interactive Elements: Filter inputs, buttons, tabs.
Backgrounds: Page background, section borders, shadows.

What CSS Cannot Style (Charts)¶

Chart Internals: Bars, lines, axes, legends inside the Vega-Lite charts.
PDF Exports: Static exports use a different rendering path where external CSS may not apply fully.

Recommendation: - Use Style Options (a chart's own style.color, chart.style) for chart colors and axes. - Use Custom CSS for layout, typography, and branding of the surrounding page.

Chart-Level Styling¶

Override theme for specific charts:

charts:
  custom_chart:
    title: "Custom Styled Chart"
    query: sales
    type: bar
    x: month
    y: total_revenue
    style:
      color:
        categorical:
          palette: editorial-10   # A built-in categorical palette
      legend:
        visible: true             # Show legend (default)
      axis:
        grid:
          visible: false           # Hide grid lines

Chart styles are sparse overlays on the active theme. An omitted field inherits the nearest theme or board-level value. An explicit null clears a nullable value; for example, legend.symbol_limit: null removes an inherited entry cap. Using null for a required resolved value, such as legend.columns, fails validation instead of silently inheriting.

Style Options¶

Color Palettes¶

Choose from built-in color palettes:

editorial-10 - Default categorical palette: blue-first ten-color set tuned for calm, editorial multi-series charts
vivid-10 - Higher-saturation ten-color categorical set
tableau - Tableau-style 10-color set, for users who want the familiar hues
dbt-seq-blue - Blue sequential palette (light → dark)
dbt-seq-green, dbt-seq-amber, dbt-seq-rust, dbt-seq-teal, dbt-seq-purple, dbt-seq-brown - Single-hue sequential palettes
dbt-seq-gray - Achromatic sequential palette (magnitude without hue)

Choosing a palette: - Categorical data: Use editorial-10 or another categorical palette - Sequential data: Use a dbt-seq-* palette - Accessibility: Consider colorblind-friendly palettes

The full catalog, including diverging palettes, tonal category sets, and dark-theme companions, is in the Palettes guide.

dbt Charts Palette Direction¶

Alongside the generic built-in schemes above, dbt Charts now documents its own chart-library palette direction:

the default dbt Charts categorical palette is a blue-first ten-color set tuned for calm, editorial multi-series charts
single-series charts (one mark, no color encoding) inherit the active theme's single-series ink (for example, dark blue on clarity, warm dark brown on paper) instead of falling back to the categorical palette's anchor
hero-6 is a hero-blue-versus-neutrals palette for charts where one series should dominate

See Palettes for the full catalog with swatch previews.

A neutral single-series mark¶

Every theme's single-series ink is a color (dark blue on clarity, warm dark brown on paper) because most boards want a chart's one mark to read as data, not chrome. When a chart genuinely encodes nothing by hue and a neutral mark communicates that more honestly, pin single_series_palette to a gray scaffold step instead.

At board scope, every single-series chart on the board goes neutral:

style:
  charts:
    color:
      categorical:
        single_series_palette: [dbt-grays.heading]

At chart scope, only the one chart goes neutral; a static color skips the palette-slot machinery entirely, since a single-series chart never has more than one slot to skip:

style:
  color:
    static: dbt-grays.heading

Legend¶

Control legend display per chart (within a chart's style: block):

charts:
  my_chart:
    type: bar
    style:
      legend:
        visible: false  # Hide legend

Top-horizontal legends hide their title automatically because the color-channel name is usually redundant. Set title.visible: true to opt in when the title adds useful context:

charts:
  my_chart:
    type: bar
    style:
      legend:
        position:
          edge: top
        title:
          visible: true   # opt in; omitted means hidden for this layout

For other legend layouts, title.visible: false hides only the title while keeping the color swatches.

direction is inferred from position.edge: top and bottom legends are horizontal, left and right are vertical. Author direction to override. An inferred-horizontal legend too wide for one row wraps at compact_columns; author direction or columns to opt out.

Automatic compact top legends and wrapped horizontal legends use compact_columns from the active legend style (the base theme uses two). Set a positive integer on a chart's legend style to tune that automatic wrapping; columns: 0 leaves ordinary legends on the renderer default.

style.legend is not supported on kpi or table charts; neither renders a color legend, so authoring it is a validation error.

values pins an explicit legend entry order and filter; see Legend for the full resolution rules (matching a column name against its rendered label, and what happens when an entry doesn't resolve):

charts:
  my_chart:
    type: bar
    style:
      legend:
        values: ["Paid", "Organic", "Referral"]

Grid Lines¶

Show or hide grid lines per chart (within a chart's style: block):

charts:
  my_chart:
    type: bar
    style:
      axis:
        grid:
          visible: true    # Show grid lines
          # visible: false  # Hide grid lines

Ratio-percent bar, line, area, and scatter charts automatically emphasize the unity baseline at y=1 when the effective y-domain includes that value. This is the common 100% guide for retention, conversion rate, and NRR charts stored as ratios such as 1.08. Style the rule with the existing axis_y.grid.threshold color and width settings, or hide it on its own with grid.threshold.visible: false, which leaves the axis's other gridlines in place:

charts:
  nrr:
    type: line
    style:
      number_format: percent_whole
      axis_y:
        scale:
          continuous:
            domain: [0.95, 1.2]
        grid:
          threshold:
            width: 3
            # visible: false  # hide the threshold rule only

The same grid.threshold style block is authorable on any axis slot, not just axis_y. A chart with its own quantitative x column, a scatter plotting one ratio against another for example, earns an independent zero or unity rule on that axis too; style or suppress it the same way, scoped to axis_x.grid.threshold.

Holding an Axis Still Across Filter Changes¶

A chart's measure axis is scaled to the rows its query returned, so changing a filter variable rescales it; the same value can land at a different pixel before and after the change. When viewers compare values across filter selections, pin the bounds yourself with an explicit domain:

charts:
  quarterly_revenue:
    type: bar
    x: month
    y: revenue
    style:
      axis_y:
        scale:
          continuous:
            domain: [0, 800]   # same frame of reference for every selection

An authored domain wins over every other axis-scaling behavior; headroom and the zero-baseline heuristic both step aside for it.

Axis Labels¶

Hide axis labels with labels.visible: false:

style:
  axis_y:
    labels:
      visible: false   # hide y-axis labels entirely

This matches the existing convention for other axis elements (grid.visible, line.visible, ticks.visible).

Suppressing the axis title alongside `x_label`/`y_label`¶

style.axis_y.title.visible / style.axis_x.title.visible control whether the axis title itself is drawn. Authoring x_label/y_label normally forces the axis title on (it overrides the theme's default suppression so the label has somewhere to show up), but an explicit title.visible: false authored anywhere on the chart (style.axis_y/style.axis_x, the type-conditional style.axis_quantitative/style.axis_band, or the chart's shared style.axis patch) still wins and suppresses just the on-axis text. The label keeps doing its other jobs (the tooltip and any endpoint/rail labels), so y_label: "% from Data Lakes" plus axis_y.title.visible: false is a legal, supported combination for a chart that wants the label without the axis-title space it reserves.

This precedence holds for a board-level override too: a style.charts.axis_y.title.visible: false set once on the board suppresses the axis title on every chart, even those that author y_label. An explicit title.visible you author, whether on the board or on a single chart, always wins over the label-forcing default; a chart-level override just narrows the effect to that one chart.

Label density¶

Three knobs control how densely labels are packed on an axis:

labels.overlap: two switches for resolving overlapping x-axis labels. On temporal axes dbt Charts tries skip before tilt. For bucketed temporal axes, skip shows labels at the next meaningful calendar boundary while leaving the axis, label-format time unit, and ticks unchanged. A resolved coarser labels.time_unit, whether authored or chosen automatically, also sets the default tick cadence. Categorical axes never skip because every category label carries domain information; they only use an authored font size and tilt. If the automatically thinned labels still do not fit, tilt rotates them through tilt_increments, shallowest first. Font size never changes.

Quantitative x-axes bypass overlap resolution because Vega-Lite places their continuous-scale ticks.

labels.min_gap: minimum pixel gap between adjacent label bounding boxes before they count as non-overlapping (default 16). Only active when overlap resolution is on. Raise it to add visible breathing room between retained labels.

labels.max_width: maximum pixel width before a label is truncated with … (Vega-Lite default 180px). Tighten for narrow charts; loosen for charts with long category names.

style:
  axis_x:
    labels:
      overlap:
        skip: true
        tilt: true
      min_gap: 24
      max_width: 120

Positioning and boundary¶

Three knobs control where a label sits relative to its tick and whether it survives clipping at the axis range edges.

bound: hide labels whose bounding boxes overflow the axis range.

Reach for it when a categorical x-axis has one very long label at the first or last position that bleeds into the chart padding or off the canvas. Accepts true (hide any overflow) or a pixel tolerance (hide only when overflow exceeds that many pixels).

charts:
  product_revenue:
    type: bar
    x: product_name     # categorical, some labels very long
    y: revenue
    style:
      axis_x:
        labels:
          bound: true   # hide labels that bleed past chart edge

flush: align the first and last labels flush with the scale range rather than centered on their tick.

Reach for it when time-series edge labels ("Jan 2022" / "Dec 2024") get clipped at chart edges. Note: Vega-Lite defaults differ by axis: true for x, false for y. Accepts true/false or a pixel tolerance (flush only when label exceeds by more than that many pixels).

style:
  charts:
    axis_y:
      labels:
        flush: true     # opt y-axis into flush alignment (VL default is false)

charts:
  monthly_revenue:
    type: line
    x: month
    y: revenue
    style:
      axis_x:
        labels:
          flush: 4      # flush only if label exceeds scale edge by more than 4px

offset: pixel offset of the label from its tick anchor.

Reach for it when fine-grained nudging is needed, for example when axis_x.ticks.offset shifts the ticks themselves or when bar-band tick positioning leaves labels misaligned with bar centers. Negative values move labels toward the chart interior; positive toward the chart edge.

charts:
  weekly_signups:
    type: bar
    x: week
    y: signups
    style:
      axis_x:
        labels:
          offset: -3    # nudge labels 3px toward chart interior

Format names and aliases¶

All named format identifiers in dbt Charts fall into one of two categories: engine-predefined names (owned by the engine, resolved with house rules) and custom project aliases (defined in style.formats: a d3 spec, a predefined name, or a format block).

Engine-predefined names¶

The following names are built into the engine. Authors write them in any format: field. They cannot be defined or overridden in style.formats; the engine owns their behavior.

format: slots take either kind: the column decides whether a date or a number is being painted. The two slots that name their own kind do not: number_format: takes only the numeric names below, and time_format: only the time ones (or a raw strftime spec like %b %Y). Crossing them raises ERR-FORMAT-KIND-MISMATCH at compile: time_format: currency resolves to the d3 number spec $,.2f, which paints a date axis with garbage rather than failing. Your own style.formats aliases are exempt; the engine cannot know which kind they target, so they stay legal in every slot.

Numeric formats:

Name	Example output
`currency`	$1.23 M
`currency_whole`	$1,235
`currency_full`	$1,234.57
`percent`	12.3%
`percent_whole`	12%
`percent_delta`	+12.3%
`integer`	1,235
`delta`	+31
`number`	1.23 M
`number_full`	1,234.57
`year`	2025

The bare name compacts; the _full suffix spells the number out. currency and number are the names to reach for on a dashboard, where a label has to be read at a glance. currency_full and number_full are for the surfaces that must show every digit: a reconciliation view, a billing breakdown, anything that has to tie out against a source system. currency_whole and integer drop the minor unit at every magnitude.

currency and number apply SI notation for large values, rounded to three significant digits with trailing zeros trimmed: 50752.9 renders as $50.8 K. A raw d3 ~s spec is not the same thing: d3's own default is six significant digits, so format: "$~s" gives $50.7529 K. (Both shown in the same analytic register here; a literal $~s authored inline also renders in d3's native register, $50.7529k, as described under Format aliases.)

percent, percent_whole, and percent_delta expect a 0–1 ratio; the engine multiplies by 100 before formatting, so 0.182 renders "18.2%". percent and percent_whole refuse a 0–100-shaped value outright rather than paint "1820%" (ERR-PERCENT-RANGE); divide by 100 before it reaches the chart. percent_delta is exempt, because a delta legitimately runs past 100%.

year is an identifier, not a quantity. Every other numeric name groups digits or scales by magnitude; a year should have neither (2,025 and 2.025 K are both wrong for a year). year renders plain integer digits with no grouping.

Engine-only formats (handled directly by the engine, not through a format spec; valid on KPI and table format slots only, not on Vega-rendered slots such as axis labels, mark value labels, number_format, time_format, or support_table):

Name	Behavior
`percent_number`	Formats `27.6` as `27.6%` (value is already a percentage)
`percent_number_delta`	Formats `+3.2` as `+3.2%` with sign (value is already whole percent)
`percentage_points_delta`	Formats `+1.5` as `+1.5 pts` with sign. Input is whole points, not a fraction: a delta of `0.575 - 0.47` renders `+0.1 pts`; multiply by 100 in the query

Time formats: the whole vocabulary time_format: accepts, beside a raw strftime spec:

Name	Example output
`date_short`	7 Mar 2024

Using predefined names in charts¶

charts:
  revenue:
    type: bar
    x: month
    y: revenue
    style:
      number_format: currency    # engine-predefined name

  conversion:
    type: bar
    x: date
    y: rate
    style:
      number_format: percent     # engine-predefined name

  raw_d3:
    type: bar
    x: month
    y: amount
    style:
      number_format: "$,.0f"     # raw D3 spec; passes through unchanged

Custom project aliases (`style.formats`)¶

Add style.formats at the theme or board level to define project-specific short names. Board keys override theme keys; theme keys not redefined by a board propagate through unchanged.

Restyle every chart at once by redefining an engine name. number, currency, percent, date_short and the other engine names are keys like any other. Every axis, tooltip, mark label, table cell, KPI value and data-table strip with no format of its own reads the board's definition:

style:
  formats:
    currency: "$,.0f"
    number: ",.0f"
    date_short: "%b %Y"

A chart's number_format, a slot's format: and an axis's labels.format still win. A redefined name prints exactly the spec you wrote, at every magnitude: the engine's rules for that name (compaction, trimmed zeros, and the switch to currency_full / number_full below 1) no longer apply, so a redefined currency of $.3~s prints $670m for 0.67. Redefine currency_full or number_full too and the engine's own currency and number use yours below 1. A redefinition must stay the same kind as the name: a date spec under currency raises ERR-FORMAT-KIND-MISMATCH.

In a theme YAML:

style:
  formats:
    revenue: "$~s"       # project-specific alias
    arr: "$,.0f"
    cost: ",.2f"

In a board YAML (adds or overrides for this board only):

style:
  formats:
    arr: "$,.2f"    # override theme's arr alias for this board

An alias to a literal d3 spec resolves with no house post-processing. An alias to a predefined name keeps that name's house rules, so a block can name a house format with an affix:

style:
  formats:
    eur:
      spec: number
      prefix: "EUR "

An alias target that is none of these raises ERR-FORMAT-INVALID at compile time.

Any string that isn't a known name or alias is tried as a raw d3 format spec. number_format: "$,.0f" is a supported escape hatch for cases where none of the named presets fit; it passes through unchanged and is validated as a legal d3 string at compile time.

Non-dollar currencies: the `FormatConfig` object form¶

Every format: field above -- number_format, an axis's labels.format, axis_y.mirror.format, a mark's labels.format/ total_label.format, a layer's own axis_y.labels.format, a support_table entry's format, and each value in style.formats -- also accepts an object instead of a string:

style:
  axis_y:
    labels:
      format:
        spec: ",.0f"      # a raw d3 spec, or an engine-predefined name
        prefix: "€"       # or: suffix: " EUR"

d3's own grammar admits only $/# as a spec's own currency symbol (https://d3js.org/d3-format), so any other currency mark -- €, £, or a spelled-out code like " EUR" -- is authored as prefix/suffix instead of embedded in spec.

Sign placement. sign_placement: before_prefix puts a negative sign ahead of the prefix (−€500); after_prefix puts it between prefix and digits (EUR −500). Unset, a prefix ending in a space (a word or code) takes after_prefix, any other prefix before_prefix. Where the prefix paints on one value only (see repeat), the sign always follows it, so the anchor's digits line up with the bare values beside it (€−50 above −40); before_prefix there raises ERR-FORMAT-SIGN-BEFORE-ANCHORED-PREFIX. A suffix always trails the digits (−500 EUR). A table column keeps the sign against the digits (€ −500) because its prefix lane is shared down the column, so sign_placement on a table column raises ERR-FORMAT-SIGN-PLACEMENT-TABLE-UNSUPPORTED.

Repeat. repeat: anchor paints the prefix and suffix on one value per axis, table column or support_table row; the engine picks which. repeat: every paints them on every value. Unset keeps each surface's default: a vertical axis and a symbol_mode: anchors table anchor, a horizontal bar's value axis repeats, and a support_table row anchors a predefined format's affix where its cells have an order. Value labels, totals, tooltips and KPIs show one value, so they ignore repeat.

style:
  axis_y:
    labels:
      format:
        spec: ",.0f"
        prefix: "EUR "
        repeat: anchor

A prefix/suffix combines freely with an SI spec, compacting axis and all -- a number spec with prefix: "€" paints €12.4 M on an axis exactly the way the engine's own currency preset ($.3~s) paints $12.4 M; the affix composes around the shared-magnitude ladder rather than colliding with it. A raw .3~s literal keeps d3's own register (€12.4M) unless notation says otherwise.

A prefix/suffix also composes cleanly with a spec that already carries its own native $/# symbol (a literal like $,.0f, or a predefined name like currency/currency_whole that resolves to one) -- the authored prefix comes first, then the native symbol's own body: a $,.0f spec with prefix: "US " paints US $154,500 (US −$154,500 for a negative), never $US 154,500 or a dropped prefix. This holds even when the spec is both SI-shaped and native-symbol-bearing (the currency preset, $.3~s): US $12.4 M, not one symbol silently dropped.

Restrictions. None of these targets has an expression slot to compose a prefix/suffix/notation into:

A temporal axis's format (ERR-FORMAT-AFFIX-TIME-UNSUPPORTED, caught at compile) -- a strftime spec paints through Vega's native time formatter, not d3-format's number grammar.
A categorical (nominal/ordinal) axis (ERR-FORMAT-AFFIX-NOMINAL-AXIS-UNSUPPORTED), a geo chart's tooltip (ERR-FORMAT-AFFIX-GEO-TOOLTIP-UNSUPPORTED), or a chart family excluded from the structured tooltip (ERR-FORMAT-AFFIX-NATIVE-TOOLTIP-UNSUPPORTED) -- all three fire at resolve, once the actual chart/channel type is known, not at compile.

A table column or KPI paints a date spec's affix around the date instead: a %b %Y spec with prefix: "FY " on a table column paints FY Jan 2026.

notation overrides the analytic (1.2 M, suffix stated once) vs. narrative (1.2M, repeated per value) register that currency/number otherwise pick automatically. It only affects an SI-shaped spec -- useful on a raw ~s literal with notation: narrative, which otherwise renders in d3's own native register instead of either house register. It does nothing to a date or any other non-SI spec.

An authored labels.expr overrides the axis's format entirely. When an axis carries a custom label expression, it renders exactly as written -- no prefix, suffix, or notation from the format is composed into it:

style:
  axis_y:
    labels:
      format:
        spec: ",.0f"
        prefix: "EUR "
      expr: "datum.label + ' /mo'"

Inside the expression, datum.label is Vega's own text formatted from the plain d3 spec, so a native $/# in the spec appears in it, but a FormatConfig prefix, suffix, or notation does not. Write the symbol into the expression yourself:

style:
  axis_y:
    labels:
      expr: "'EUR ' + datum.label + ' /mo'"

A surface the expression doesn't govern, like the tooltip, still paints the full format.

The object form works as a style.formats alias value too, referenced by name everywhere a string alias is:

style:
  formats:
    eur:
      spec: ",.0f"
      prefix: "€"
charts:
  revenue:
    type: bar
    x: month
    y: revenue_eur
    style:
      number_format: eur

Suppressing format with `null`¶

Use format: null (or omit format:) to suppress format emission and let VL/D3 pick its own default based on the axis scale type. This is the canonical way to override an inherited theme-level format: number per chart; no format: auto string sentinel.

Typography¶

Every piece of text on a board reads one of seven named fonts declared under style.fonts. Change a named font once and every title, label, or caption bound to it follows:

style:
  fonts:
    heading:
      family: "'Source Serif 4', Georgia, serif"
    body:
      family: "Inter"

Font	Used by
`heading`	Board titles, chart titles, markdown `#` to `######`
`subtitle`	Title subtitles
`body`	Markdown prose
`label`	Axis and legend labels and titles, tooltips, KPI labels, table cells and headers, variable controls, tabs, details
`caption`	Footers, timestamps, callout messages
`numeral`	KPI values, quantitative axis labels, support tables, pie totals
`code`	Inline and fenced code in markdown

A named font takes the same fields as any font: block (family, color, size, weight, style, decoration, case, line_height) and sets only the fields it names. A board's fonts: merge with the theme's key by key, so redefining heading keeps the theme's body.

Heading sizes¶

Heading levels H1 to H6 share the heading font and differ only in size. The sizes live on the heading font as a six-step list, sizes; heading takes no size:

style:
  fonts:
    heading:
      sizes: [30, 20, 16, 14, 11, 11]

A board title reads its level's step, markdown # reads the first step, and chart titles pick a step by card width.

Applying a named font to a slot¶

Any font: slot except the root style.font and details.arrow.font takes a named font in one of three forms:

style:
  title:
    font: heading
  charts:
    kpi:
      value:
        font:
          extends: numeral
          size: 40

By name: font: heading uses the named font as-is.
By name with overrides: extends: plus the fields that differ.
Inline: a plain font: block with no name.

An unknown name raises ERR-FONT-UNKNOWN and lists the fonts in scope. When a slot names a font, it replaces whatever a theme bound to that slot. The root style.font is the base every other font inherits from, so it rejects a name; set style.fonts.body to restyle base text.

Fonts that extend fonts¶

A style.fonts entry takes the same forms as a slot, so a font can start from another font. Define a per-role font once and bind slots to it:

style:
  fonts:
    tag:
      extends: label
      weight: 600
      case: upper
  charts:
    kpi:
      label:
        font: tag

A bare name makes an alias: small: caption is a second name for caption.

An entry is its parent's fields plus its own, and its own fields win. Chains of any length work; a cycle raises ERR-FONT-REGISTRY and names the path. sizes is the heading ramp and is never inherited. extends: null gives an entry no parent. When a board's entry sets extends, it replaces the theme's entry of the same name instead of tweaking it.

Families¶

Common font choices: - Inter - Modern, readable sans-serif - Roboto - Google's Material Design font - Open Sans - Friendly, readable sans-serif - Lato - Humanist sans-serif

Case¶

Every font slot supports a case field that applies a letter-case transform to the text before it reaches SVG or Vega-Lite output. The default is none (no transform).

Value	Behavior
`none`	No transform (default). Text is rendered exactly as authored or returned from the database.
`title`	Chicago/Gruber-style title case. Lowercases stopwords (a, an, and, at, but, by, for, in, of, on, or, the, to, via, vs.). Always capitalizes the first and last word. Preserves any token containing internal capitals: `ARR`, `MRR`, `iPhone`, `GitHub`, `SQL` are untouched.
`sentence`	Uppercases the first letter; preserves all other characters as authored. Acronyms already capitalized by the author are preserved.
`upper`	All characters uppercased.
`lower`	All characters lowercased.
`slug`	Machine identifier form: spaces/hyphens → underscore, lowercased. `Order Status` → `order_status`.
`camel`	camelCase: first word lowercase, subsequent words capitalized. `order status` → `orderStatus`.

Why smart title case matters¶

The case: title value uses the Gruber algorithm, not the naive "capitalize every word" approach shipped by CSS text-transform: capitalize, Microsoft Word, and most BI tools. The key rule: any token that already contains internal capitals is left alone. This means metric initialisms common in dashboards are safe:

ARR Growth by Segment         →  ARR Growth by Segment  (correct)
Revenue by Customer Segment   →  Revenue by Customer Segment
from the top                  →  From the Top

A naive every-word capitalizer would produce Arr Growth By Segment; editorial garbage that damages brand credibility on published dashboards.

Setting case in a theme¶

Theme authors can enforce a casing convention across all text slots by adding case: to the font block at whichever level they want it to take effect:

# In a theme YAML; title-case all chart titles, board titles, and KPI labels
title:
  font:
    case: title

charts:
  font:
    case: title

# In a board YAML; upper-case axis tick labels for this chart only
charts:
  pipeline_stages:
    type: bar
    x: stage
    y: count
    style:
      axis_x:
        labels:
          font:
            case: upper

Scope and limitations¶

case applies to static authored text and data-derived static values:

Board title and subtitle
Chart title (as emitted in the Vega-Lite spec)
KPI label text
Table header display names
Legend titles (as emitted in the Vega-Lite spec)
Error and placeholder overlay text

Axis titles are not in that list. A derived axis title is the bound column's name split into words: an all-lowercase or all-uppercase word is lowercased (REVENUE renders revenue), and a mixed-case word such as MTok keeps its spelling. An authored x_label/y_label or field_labels entry renders as written.

For data-bound tick labels and legend item labels (rendered by Vega at runtime from query results), only upper and lower are applied; they map directly to Vega expression language (upper(datum.label), lower(datum.label)). The title and sentence values have no equivalent in Vega expression language, so they cannot be applied to data-bound labels at render time.

Board markdown body text (text: blocks) is intentionally excluded; applying case to Markdown would corrupt code spans, links, and emphasis markup.

Board-Level Styling¶

Apply CSS-like styles to any board or nested layout section:

rows:
  - title: "Styled Section"
    style:
      background: "#f0f4f8"
      border: "2px solid #667eea"
      border-radius: "8px"
      padding: "16px"
      font:
        color: "#333"
    cols:
      - my_chart

Supported Style Properties¶

Property	Example	SVG	HTML	Description
`background`	`"#f5f5f5"`	✅	✅	Background color (hex, rgb, named)
`border`	`"2px solid #ddd"`	✅	✅	Border shorthand (width style color)
`border-radius`	`"8px"`	✅	✅	Corner rounding
`font.color`	`"#333"`	✅	✅	Text color. Titles and headings use it unless `title.font.color` is set.
`padding`	`"16px"`	✅	✅	Inner spacing (affects content layout)
`margin`	`"8px 16px"`	❌	✅	Outer spacing
`gap`	`"12px"`	✅	✅	Override gap between child items

Padding & Sizing¶

Padding is accounted for in layout calculations. When you add padding to a board:

The board's children have less available space
Content is properly inset from the border
Height calculations include the padding

# Padding formats (CSS-style)
style:
  padding: "16px"           # All sides equal
  padding: "8px 16px"       # Vertical, horizontal
  padding: "8px 16px 12px"  # Top, horizontal, bottom
  padding: "8px 16px 12px 4px"  # Top, right, bottom, left

Border Styling¶

Borders support the CSS shorthand format:

style:
  border: "2px solid #667eea"  # width style color
  border-radius: "8px"         # Rounded corners

Example: Styled Cards¶

Create card-style sections with backgrounds and borders:

cols:
  - text: "### Success Card"
    style:
      background: "#c8e6c9"
      border: "2px solid #4caf50"
      border-radius: "12px"
      font:
        color: "#1b5e20"

  - text: "### Warning Card"
    style:
      background: "#fff3e0"
      border: "2px solid #ff9800"
      border-radius: "12px"

Layout Sizing¶

Automatic Sizing¶

dbt Charts automatically calculates sizes based on content:

Charts: 300px default height (KPIs: 100px, Tables: 250px)
Titles: Height based on font size and text length
Markdown content: Height based on rendered text with word-wrapping

User-Specified Widths¶

In cols layouts, specify widths for individual items:

cols:
  - width: "30%"    # 30% of available width
    rows:
      - sidebar_chart
  - width: "70%"    # 70% of available width
    rows:
      - main_chart

Supported formats: - Percentages: "30%", "70%" - Pixels: "200px", "400px" - Auto (default): Remaining space divided equally

Gap Control¶

Control spacing between items:

# Per-section gap override
rows:
  - title: "Compact Section"
    style:
      gap: "8px"  # Smaller gap between children
    cols:
      - a
      - b

Content-Aware Heights¶

Heights are calculated based on content type:

Content Type	Default Height
Standard chart	300px
KPI card	100px
Table	250px
Title	Based on text
Markdown	Based on rendered content

In cols layouts, all items get the same height (maximum of their content heights) for proper alignment.

Number Formatting¶

dbt Charts uses d3-format spec strings everywhere numbers appear: chart axis labels, KPI tiles, and table cells all share the same format spec language.

Format spec syntax¶

The d3-format spec grammar is:

[[fill]align][sign][symbol][0][width][,][.precision][~][type]

Token	Meaning	Example
`fill`	Padding character (default space)	`0>10.2f`
`align`	`>` right · `<` left · `^` center · `=` sign-then-pad	`<10.2f`
`sign`	`-` minus-only · `+` always · `(` parens negatives · space	`+,.2f`
`symbol`	`$` currency prefix · `#` alternate form	`$,.2f`
`0`	Zero-pad to width	`06.2f`
`width`	Minimum output width	`10.2f`
`,`	Thousands separator	`,.2f`
`.precision`	Decimal digits (or significant figures for `s`, `g`, `r`)	`.2f`
`~`	Trim trailing zeros and decimal point	`.1~%`
`type`	Format type; see table below	`f`

Types:

Type	Description	Spec	Result
`f`	Fixed-point	`,.2f` on 1234.56	`1,234.56`
`%`	Percentage (×100 + %)	`.1~%` on 0.05	`5%`
`p`	Percentage to significant digits	`.1p` on 0.1234	`10%`
`e`	Exponential	`.2e` on 1234.56	`1.23e+3`
`s`	SI prefix	`~s` on 1500000	`1.5M`
`g`	General (shorter of `e`/`f`)	`.3g` on 0.001234	`0.00123`
`r`	Rounded significant digits	`.2r` on 12.56	`13`
`d`	Integer	`d` on 12.9	`13`
`n`	Locale number (same as `,g`)	`n` on 1234	`1,234`
`b`	Binary	`#b` on 255	`0b11111111`
`o`	Octal	`#o` on 255	`0o377`
`x` / `X`	Hex, lower / upper	`#x` on 255	`0xff`
`c`	Character data (verbatim)	`c` on 1234.5678	`1234.5678`

Every d3-format type works in every format slot: axis labels, KPI tiles and table cells all resolve the same grammar, so a spec that renders on an axis renders identically in a KPI.

Bad specs fail at compile. A format string that is not a predefined engine name, a style.formats alias, or a valid d3-format spec fails dct validate and dct render with ERR-FORMAT-INVALID, pointing at the line and offering a "did you mean" hint, so a typo like percent_1 is caught before anything renders, not dropped silently.

B-for-billion divergence. dbt Charts's Python formatter (KPI tiles and table cells) maps the SI giga prefix G to B so that 1.5G displays as 1.5 B. Chart axes use real d3.js in the browser, which emits G. This is a deliberate dbt Charts extension. The number format rounds to 3 significant figures and uses k/M/B/T with a space separator in dbt Charts (vs k/M/G/T with no space in d3).

For the full d3-format reference see https://d3js.org/d3-format.

Numeric display conventions¶

dbt Charts's defaults for numeric display on dashboard surfaces. The d3 spec language above is the mechanism; the conventions below are the house style that governs which spec to reach for.

Prefer predefined names over raw d3 specs. Use currency, currency_whole, currency_full, percent, percent_delta, integer, delta, number from the engine-predefined set (Format names and aliases above). Raw d3 specs only when no predefined name fits, for example, sub-1% percent precision needs ".2%". Raw specs work, but a board full of them is harder to read and won't benefit from future engine improvements to the house formatters.

KPI support deltas without a glyph: use format: delta, not integer. format: integer (,.0f) drops the sign on positive values; a support value of +31 renders as bare 31, direction-blind. format: delta (+,d) forces the leading sign on positive values (d3 emits the minus sign on negatives either way). Reserve integer for values that are not deltas (counts, totals). When the KPI already carries a directional glyph (▲/▼ via style.glyph.character), the icon communicates direction and either format reads fine.

Currency: reach for the bare name. format: currency ($.3~s) is the dashboard default ($1.2 M, $47) because the digits below the top three add precision a reader doesn't use at a glance and crowd KPI rails and table columns. format: currency_whole ($,.0f) writes the number out without cents. Reserve format: currency_full ($,.2f) for surfaces that demand reconciliation accuracy: billing breakdowns, financial statements, reports where exact match-to-source matters. Negative currency uses a minus prefix (-$1,234), not accounting parens.

Two notation families ship with the theme.

Family	Form	Use for
Analytic	`$2.5 M`, space before suffix, uppercase `K`/`M`/`B`/`T`	Dashboard chrome: axes, KPIs, dense tables, tooltips
Narrative	`$2.5mn`, no space, lowercase `k`/`mn`/`bn`/`trn`	Prose surfaces: text cards, annotations, page/section/chart titles

Theme choice (clarity, neon, etc.) is visual identity. Notation family is independent; a narrative-feeling theme can still use analytic notation in its axes.

Precision is a group decision. The reader's context (a single headline KPI vs. a long table column) determines how much precision is tolerable as much as the value's magnitude does. Magnitude sets the default; surface modulates.

Default by magnitude:

Range	Format	Examples
≥ 20%	whole percent	`23%`, `47%`, `89%`
1–20%	one decimal (`percent`)	`1.2%`, `8.7%`, `12.5%`
< 1%	two decimals (raw d3 `".2%"`)	`0.12%`, `0.045%`

Modulate by surface. A single headline KPI or short rail (1–4 values) can afford one more decimal than the band default; there's nothing to scan against. A long table column or axis (>10 similar-magnitude values) is a real tradeoff: whole-percent aids scan-uniformity and distribution reading; the band default's precision aids close comparison across rows. The right call depends on the column's actual use: distribution scan favors the simpler form, close comparison favors keeping the decimal. Adjacent surfaces showing the same metric may format differently: a reconciliation table at .0% while its headline KPI shows .1%.

Meaningful-precision override. Some metrics carry signal in tenths of a percent regardless of magnitude or surface: A/B test conversion rates (4.27% vs 4.31% is a 1% relative lift), MoM churn at basis-point resolution, conversion rates in a tight range. For these, use ".2%" regardless of band. Precision is fundamentally a data-layer call; if the data carries signal in tenths or hundredths, the chart should show it.

Zero values strip trailing decimals, even when siblings have them. Render 0, $0, 0%; never 0.00, $0.00, 0.0%. A $0 KPI picks format: currency_whole even if its partner KPI uses format: currency for sub-dollar precision. The value is exactly zero; sibling-matching decimals fake precision the data doesn't have.

NULL renders as — (em-dash), never as 0. They are different claims about the data.

A KPI whose query returns zero rows raises an error. A silent 0 or — hides a real problem (broken query, empty filter, wrong source).

Tables anchor the currency symbol. Default symbol_mode: anchors puts $ on the first row of a column; rows below omit it. The first row anchors the column for the rows below.

Compaction is a column-level decision, not per-value. Compact when ≥4 similar-magnitude values exceed 10,000, or when surface density demands it. With 2–3 values the longer form usually reads fine. Adjacent surfaces showing the same metric may compact differently: a reconciliation table can show full precision while the headline KPI compacts.

Best Practices¶

Consistent Styling¶

Use the same color palette throughout a dashboard
Keep font choices consistent
Use grid lines consistently (all on or all off)

Accessibility Considerations¶

Choose colorblind-friendly palettes
Ensure sufficient contrast
Use labels and legends for clarity

Color Choices¶

Categorical data: Use distinct colors (editorial-10)
Sequential data: Use gradient palettes (dbt-seq-blue, dbt-seq-green)
Avoid: Too many colors (5-7 max for clarity)

Performance¶

Styling has minimal performance impact
Use global style when possible (more efficient)
Override only when necessary

Charts - Chart styling options
Boards - Layout and organization

Styling¶

Themes¶

Title and header overflow¶

Styling every chart's title¶

Vega-Lite Config Overrides¶

Global Styling¶

Style Options¶

Data-freshness stamp¶

Markdown text styling¶

Border & Corner Styling¶

Emoji handling¶

CSS Scope & Limitations¶

What CSS Can Style (HTML)¶

What CSS Cannot Style (Charts)¶

Chart-Level Styling¶

Style Options¶

Color Palettes¶

dbt Charts Palette Direction¶

A neutral single-series mark¶

Legend¶

Grid Lines¶

Holding an Axis Still Across Filter Changes¶

Axis Labels¶

Suppressing the axis title alongside x_label/y_label¶

Label density¶

Positioning and boundary¶

Format names and aliases¶

Engine-predefined names¶

Using predefined names in charts¶

Custom project aliases (style.formats)¶

Non-dollar currencies: the FormatConfig object form¶

Suppressing format with null¶

Typography¶

Heading sizes¶

Applying a named font to a slot¶

Fonts that extend fonts¶

Families¶

Case¶

Why smart title case matters¶

Setting case in a theme¶

Scope and limitations¶

Board-Level Styling¶

Supported Style Properties¶

Padding & Sizing¶

Border Styling¶

Example: Styled Cards¶

Layout Sizing¶

Automatic Sizing¶

User-Specified Widths¶

Gap Control¶

Content-Aware Heights¶

Number Formatting¶

Format spec syntax¶

Numeric display conventions¶

Best Practices¶

Consistent Styling¶

Accessibility Considerations¶

Color Choices¶

Performance¶

Related¶

Suppressing the axis title alongside `x_label`/`y_label`¶

Custom project aliases (`style.formats`)¶

Non-dollar currencies: the `FormatConfig` object form¶

Suppressing format with `null`¶