Skip to content

Bar Charts

Bar charts encode values as lengths measured from a common baseline, which makes them one of the most fundamental tools for comparison; this family includes horizontal bar charts and vertical column charts. Horizontal bars are especially good for ranking categories with long labels, while vertical columns are especially good for showing change over simple time steps.

dbt Charts bar charts use a small set of top-level shorthand fields together with style. By default, style.orientation is auto: dbt Charts picks horizontal for categorical x (nominal/string labels) and vertical for continuous x (temporal, quantitative, date-like ordinal, or time-unit bucketed). The rule is type-driven, not viewport-driven: orientation reflects what the data is, not how wide the chart happens to be. Set style.orientation: vertical or style.orientation: horizontal to lock in a specific orientation. See Axis Labels: Smart Layout for how the engine picks orientation and label tilt automatically when style.orientation is left at its default.

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 default ownership and lower-level property coverage, see the YAML Schema Reference.


Minimum Required for a Bar Chart

These are the minimum fields required to render a basic bar chart in dbt Charts. With a nominal x-axis (category strings), the default result is a horizontal bar chart; with a continuous x-axis (temporal, quantitative, or date-like ordinal), the default is a vertical column chart. See Axis, Scale, and Orientation for the rule, or set style.orientation explicitly to override.

dbt Charts field Maps to Vega-Lite Allowed values Notes
query data.values Query name or query reference Supplies the dataset.
type: bar mark.type: "bar" Literal bar Selects the bar mark.
x encoding.x.field Field name Category, discrete field, or temporal field.
y encoding.y.field Field name Numeric measure to compare.

Minimum Example

source: examples_db
charts:
  product_revenue_columns:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - product_revenue_columns
Revenue by Product00.5m1m1.5mWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Top-Level Chart Fields

These are the top-level chart properties you set directly on a bar chart before you get into nested properties under style.

dbt Charts field Maps to Vega-Lite Allowed values Notes
query data.values Query name or query reference Query results become the plotted dataset. Use pre-aggregated data with one row per plotted key.
type: bar mark.type: "bar" Literal bar Standard bar or column chart.
x encoding.x.field Field name Usually the category field, or a temporal field for time-unit column charts.
y encoding.y.field Field name or list of field names Usually the numeric measure, even when the final chart is horizontal. A list creates layered multi-metric bars.
title title.text String Chart title.
notes metadata String AI search/context metadata. Never rendered.
color encoding.color.field Field name Adds series grouping or composition.
x_label encoding.x.title String Custom x-axis title.
y_label encoding.y.title String Custom y-axis title.
field_labels legend, tooltip and axis titles Map of column to text Display text for a column, painted as written. See Field Labels.
tooltip hover card rows List of column names or {column, label, format} Query columns to add to the hover card. See Add columns to the tooltip.
format quantitative value-axis format Format string Numeric formatting for the value axis. In horizontal bars, that value axis is rendered on x.
sort categorical axis sort Sort object Most useful for ranked bar charts.

Vertical Columns and Horizontal Bars

This example shows the family's two main forms side-by-side: a vertical bar chart (also called a column chart), and the same data rendered horizontally. Both pin style.orientation explicitly so the contrast is what's on the page; left at auto, this nominal x would render horizontal by default.

source: examples_db
queries:
  sales_by_product:
    sql: |
      SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
charts:
  product_revenue_columns:
    query: sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    style:
      orientation: vertical

  product_revenue_bars:
    query: sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    style:
      orientation: horizontal
rows:
  - product_revenue_columns
  - product_revenue_bars
Revenue by ProductWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z0   ​0.5   ​1   ​1.5MRevenue by Product00.5m1m1.5mWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Labels and Ranking

This example keeps the chart definition compact while showing the top-level fields most readers use in practice: labels, formatting, and sorting.

source: examples_db
charts:
  ranked_products:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Top Products by Revenue
    notes: A sorted product ranking shown as horizontal bars.
    x: product
    y: revenue
    x_label: Product
    y_label: Revenue
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
      axis_y:
        labels:
          format: currency_whole
rows:
  - ranked_products
Top Products by Revenue0$500,000$1,000,000$1,500,000RevenueWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget ZProduct Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

What sort: Does When a Category Holds Several Rows

sort: orders categories, and a category with a color series or a y: [...] list holds more than one row, so the sort column is folded to a single value per category before the categories can be ranked. Two rules cover it:

  • A stacked bar sorted by its own measure ranks by the stacked total. That is the only reading of a sort: naming revenue on a stack: zero chart whose y is revenue: the bar's length is the total. A y: [...] list does not qualify, since no single column is the measure there.
  • Every other sort ranks by the column's own value. A sort by an ordering key (release_seq, stage_rank) ranks by that key whatever the row count; a category holding one series does not sort ahead of a category holding three. The same holds for a grouped bar sorted by its measure: the fold follows whether the chart stacks, not how the bars are drawn, so with stack: none the categories rank by each one's smallest series rather than by the group's total. Sort by a pre-summed column in the query when you want the group total.

sort.by must name a column on every row of the query result; a missing column fails with ERR-SORT-FIELD-NOT-FOUND rather than rendering in natural order.

The rule is the same in both orientations, and the key column does not need to be a measure: a text or date column is an ordering too. On a multi-series bar it does cost the endpoint-label rail, which steps aside to a legend for a non-numeric sort: (see When a bar falls back to a legend instead).

Layered Multi-Metric Bars

When y is a list, dbt Charts creates a layered bar chart. This is most useful when the metrics share a similar scale and the comparison is more important than stacking.

queries:
  product_metrics:
    columns: [product, revenue, profit]
    values:
      - ["Gadget X", 18350, 4200]
      - ["Gadget Y", 30490, 7600]
      - ["Tool Z", 34900, 9100]
      - ["Widget A", 66300, 18500]
      - ["Widget B", 85680, 24100]

charts:
  layered_product_metrics:
    query: product_metrics
    type: bar
    title: Revenue and Profit by Product
    x: product
    y: [revenue, profit]
rows:
  - layered_product_metrics
Revenue and Profit by ProductProfitRevenue020k40k60k80kGadget XGadget YTool ZWidget AWidget B Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Style Fields

Use style for dbt Charts shorthand properties that affect presentational defaults such as legend visibility and gridlines.

dbt Charts field Maps to Vega-Lite Allowed values Notes
style.legend.visible encoding.color.legend true or false Typed legend control. false hides the legend.
style.axis.grid.visible axis grid visibility true or false false hides gridlines. Use style.axis.grid.visible: false (nested under grid:).
style.background chart SVG background wrapper Color value Applies a chart-level background fill behind the rendered SVG.

Legend and Gridlines

This example shows the small style surface for bar charts without changing the underlying data bindings.

source: examples_db
charts:
  category_columns_styled:
    query:
      sql: |
        SELECT category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY category ORDER BY revenue DESC
    type: bar
    title: Revenue by Category
    x: category
    y: revenue
    color: category
    style:
      stack: zero
      legend:
        visible: false
      axis:
        grid:
          visible: false
rows:
  - category_columns_styled
Revenue by Category01m2m3m4mElectronicsAccessoriesTools Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Axis, Scale, and Orientation

All presentation config lives under style. This is where the family distinguishes default vertical columns from horizontal bars.

dbt Charts field Maps to Vega-Lite Allowed values Notes
style.orientation bar orientation transform auto (default), vertical, or horizontal auto picks horizontal for categorical x, vertical for continuous x (temporal/quantitative/date-like ordinal); vertical and horizontal lock the orientation.
style.axis_x config.axisX / encoding.x.axis AxisStyle object Per-axis styling (format, ticks, labels, grid, title).
style.axis_y config.axisY / encoding.y.axis AxisStyle object Per-axis styling.
style.axis_y.scale config.axisY.scale ScaleStyle object Y-axis scale config (zero, nice, domain, clamp). Use axis_x.scale for categorical band padding.
style.stack encoding.y.stack "none", "zero", "normalize", "center" Stacking behavior. Omit stack when a color field is present to get the default side-by-side grouped layout. Set "none" for grouped (side-by-side), "zero" for stacked-from-baseline, "normalize" for 100% stacked, "center" for diverging stacks. (Within-group spacing of grouped bars is controlled by style.overlap, not stack.)
style.stack_order encoding.order "value" (default), "data", "alphabetical" Z-order of stacked segments. "value" puts the largest aggregate at the baseline. "data" stacks series in first-appearance order: SQL row order for color, the listed order for y: [a, b, ...] (a measure null in the first rows appears later). "alphabetical" sorts by series name. Ignored when stacking is off or there is only one series.
style.overlap bar xOffset/yOffset spacing "auto" (default), "none", "flush", "partial", "full", or a number Within-group spacing for grouped bars (a color field, not stacked). "auto" adapts to the series count: partial (25% overlap) at 2 series, none (small gap) at 3+. "none" gaps, "flush" touches, "partial" overlaps 25%, "full" coincides when each category holds one color (as in a waterfall) and is an error otherwise. A number is a fraction of bar width: >0 overlaps, 0 touches, <0 gaps. Positive overlap is only valid for 2 series: overlapping 3+ series buries the middle one, so it raises an error (use none/flush for 3+, or rely on auto). Setting any overlap with an active stack mode ("zero"/"normalize"/"center") is also an error.
style.grouped.padding_inner, style.grouped.padding_outer band scale paddingInner/paddingOuter float (0–1) Grouped bars only. Gap between groups and margin at both plot edges, as a share of the band step. Default 0.2 each.
style.marks.bar.band_width mark.width.band float (fraction of the band, 0–1) Fraction of the available band each bar fills. Lower it to thin bars out and open up whitespace between categories without changing overlap, which only governs spacing within a grouped-color band.

| style.marks.bar.max_size | mark.width | float (pixels) | The thickest a bar may be. Caps a band-scale bar's band_width fraction on wide charts and a continuous scale's computed width; unset, category bars stay uncapped and a continuous scale caps at 20. An authored size wins over it. |

Bar Width

This example thins the bars to 40% of their band, leaving visible whitespace between categories.

source: examples_db
charts:
  product_revenue_thin:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: bar
    title: Product Revenue
    x: product
    y: revenue
    style:
      marks:
        bar:
          band_width: 0.4
rows:
  - product_revenue_thin
Product Revenue00.5m1m1.5mWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Orientation and Axis Controls

This example uses style to turn a column chart into a horizontal ranking chart while also adjusting axis formatting and label space.

source: examples_db
charts:
  product_revenue_ranked:
    query:
      sql: |
        SELECT product, category, SUM(revenue) AS revenue, SUM(units_sold) AS units_sold FROM ecommerce_orders GROUP BY product, category ORDER BY revenue DESC
    type: bar
    title: Product Revenue Ranking
    x: product
    y: revenue
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
      axis_x:
        labels:
          max_width: 140
      axis_y:
        scale:
          nice: true
        labels:
          format: currency_whole
rows:
  - product_revenue_ranked
Product Revenue Ranking0$500,000$1,000,000$1,500,000$2,000,000Widget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Endpoint Labels and the Top-Row Series Rail

A multi-series bar names its series on the chart, anchored to each segment, rather than in a side legend. A grouped (unstacked) vertical bar's label reads the series' last value, in the value axis's own number style, then its name (wrapping onto a second line when it is too wide; if a label does not fit in two lines or the rail runs out of vertical room, every label on the rail drops its value, so the rail never mixes labels with and without values, and a warning names the series that forced it; if the names would be cut even without their values, the values stay and only the end of the second line is cut, with a warning); a stacked bar's label is the name alone, because a segment's midpoint is not the series' value. This is the default on every built-in theme; you don't switch it on. Multi-series bars come from either a color channel or a y: [field_a, field_b] list; both layouts render the endpoint rail. Where the labels go depends on the orientation:

  • Vertical stacked column charts get one label per segment in a side pane, anchored to each segment's vertical midpoint in the last column that series appears in (the rightmost, for a series that runs the full width). The chart pane and label pane sit side-by-side in an hconcat.
  • Horizontal stacked bar charts get a single rail of labels above the top row of the chart: one label per series, centered horizontally on its segment's midpoint within the top categorical row. The chart pane and rail sit stacked in a vconcat. The bottom row's value axis still carries the numeric measure labels.

The asymmetry follows from the reading direction: vertical stacks read top-to-bottom along the measure axis, so per-segment side labels feel natural; horizontal stacks read left-to-right inside one row, so a single label rail above the top row is the direct equivalent.

dbt Charts field Allowed values Notes
style.legend.position.edge auto, endpoints, top, bottom, left, or right Defaults to auto on every built-in theme: the chart takes the rail wherever it can name every series, and a legend where it can't (below). A side keeps a legend there and prints no endpoint labels, at the chart, board or project (meta.yml) level; endpoints forces the rail onto a shape it steps aside from (below). style.legend.visible: false hides the legend (under auto the labels stay; beside a side, nothing names the series), and true keeps a legend: under auto it turns the labels off, and only endpoints prints both.

style.endpoint_labels styles the labels themselves: label_offset is the gap between the plot and the rail, and height is the height of the label strip above a horizontal stack.

When the label pane or rail is on, the categorical legend turns off automatically: the two would encode the same series→color mapping twice. Authoring a legend.position side, or legend.visible: true under auto, keeps the legend instead and prints no labels; edge: endpoints with legend.visible: true prints both. On the vertical layout, the y-axis also auto-flips to the left so it doesn't collide with the right-edge label pane.

On narrow cards, vertical endpoint-label text compacts to fit the available width while its automatic vertical spacing stays readable for closely ending series.

The horizontal rail has no per-label collision resolver: it measures the real, rendered position and width of every label (the actual font, at the actual pixel scale the chart draws at), and if any two adjacent labels would touch, the whole chart falls back to a legend instead of drawing a rail with overlapping text. See "When a bar falls back to a legend instead" below.

When a bar falls back to a legend instead

The rail has to be able to name every series, or it names some of them and quietly misleads. An authored sort: is fine when it sorts by a measure: each rail anchors on the rendered domain, so it follows the sort rather than refusing it. Sorting by a non-numeric column is the exception: the rail places its labels from the order the sorted axis draws, dbt Charts confirms that order only for a numeric sort column, and labels placed from the wrong order name series in the wrong place, so the chart takes a legend instead. Where it can't, the chart keeps its legend, placed above the plot, untitled, reading in the same order as the bars. A bar steps aside from direct labeling when:

  • It's grouped: explicit stack: none, or the grouped-by-default when stack is omitted and a color field is present. Every series' last bar rises from the same baseline to a similar height, so the labels collide into one another.
  • It has no color encoding and no y: [...] list: a single series has nothing to name. (y: [...] and a color: column compose: one series per column value per measure, named <value> - <measure>; see Multiple Measures by a Dimension.)
  • color: names the same field as x:, or a series is missing from the column the rail anchors on (a trailing null, say). Either way some series would go unnamed.
  • It carries multiples:: see Small Multiples.
  • The measure goes negative: a stacked segment crossing zero has no meaningful cumulative midpoint to anchor to.
  • It's horizontal and stack: center: that rail anchors on the cumulative 0..Σ axis, which the diverging center-stack domain doesn't have.
  • It has layers:: the rail walks the base chart's own series, so an overlay layer would be left anonymous.
  • It's horizontal and the rail's own labels would collide: narrow segments, long series names, or too many series for the card width can make adjacent labels overlap. dbt Charts measures the real rendered text rather than guessing, and steps aside to a legend rather than ship a colliding rail.

Writing style.legend.position.edge: endpoints on the chart itself overrides all of these: an author who asks for the rail on one of these shapes gets it, or gets a rendering error naming the conflict where the shape genuinely can't carry it.

Vertical Stacked Columns

source: examples_db
charts:
  region_revenue_by_category_vertical:
    query:
      sql: |
        SELECT region, category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY region, category ORDER BY region, category
    type: bar
    title: Revenue by Region (vertical stack)
    x: region
    y: revenue
    color: category
    style:
      stack: zero
      orientation: vertical
      legend:
        position:
          edge: endpoints

rows:
  - region_revenue_by_category_vertical
Revenue by Region (vertical stack)EastNorthSouthWest0   ​0.5   ​1   ​1.5   ​2   ​2.5MToolsAccessoriesElectronics Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Horizontal Stacked Bars

source: examples_db
charts:
  region_revenue_by_category:
    query:
      sql: |
        SELECT region, category, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY region, category ORDER BY region, category
    type: bar
    title: Revenue by Region (stacked by Category)
    x: region
    y: revenue
    color: category
    style:
      stack: zero
      orientation: horizontal
      legend:
        position:
          edge: endpoints

rows:
  - region_revenue_by_category
Revenue by Region (stacked by Category)ElectronicsAccessoriesTools00.5m1m1.5m2m2.5mEastNorthSouthWest Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Value Labels

Show the numeric value above (or inside) each bar by enabling style.marks.bar.labels.visible.

source: examples_db
charts:
  product_revenue_labeled:
    query:
      sql: |
        SELECT product, SUM(revenue) AS revenue FROM ecommerce_orders GROUP BY product ORDER BY revenue DESC
    type: bar
    title: Product Revenue
    x: product
    y: revenue
    style:
      marks:
        bar:
          labels:
            visible: true
            position: top      # above | top | middle | middle_aligned | bottom
            format: ",.0f"     # omit to inherit axis_quantitative.format (the measure-axis format, for example, ".3~s")
            font:
              color: "#6b7280"
              size: 11
rows:
  - product_revenue_labeled
Product Revenue1,753,1361,556,9401,245,3001,189,524990,944788,200574,210573,24400.5m1m1.5mWidget BWidget AGadget YGadget XTool ZWidget CTool AGadget Z Data as of 14:58 UTC on 20 Nov 2026 made withdbt Charts
▶

Visible values:

Value Effect
auto The theme default: no value labels, except that a bar too short to see keeps a 0 label so it still reads as a value
true Label every bar
false No value labels at all, the 0 of a bar too short to see included
[min, max] or last Label only the bars the anchors name, below

Position values:

Value Placement
above Outside, past the bar end
top Just inside the bar's end, the theme default
middle Centered in the bar
middle_aligned Every label at one shared height, so a row of them reads as a line
bottom Just inside the baseline end

On a stacked bar, middle centers each label in its own segment rather than in the whole stack; use it when every segment carries a value. above has no room above an individual segment, so it renders as top. middle_aligned is not meaningful per-segment and raises an error; use middle.

On vertical bars, a label whose segment is too short to hold it is dropped rather than drawn across its neighbors, so a stack with one thin band shows the labels that fit and omits the one that does not.

To label plain bars inside their top but give a stack one total outside it, set labels.stacked: false and total_label.visible: true: stacked segments go unlabeled while total_label marks each stack, and plain bars keep their labels.

To label only some bars, set visible to a list of anchors: min and max work on any bar chart, while first and last need a time axis, because a categorical axis has no first or last bar and the chart raises an error. On a time axis first and last mean the dates, whichever order the bars are drawn in. A tie labels every tied bar, and a bar that two anchors name prints once.

On a stacked bar (stack: zero), anchors pick whole stacks by their total and print that total above the stack, so [max] prints one number and [min, max] two. A stacked bar's anchors refuse labels.field, a visible total_label (which already prints every total), and normalize or center stacks. A grouped bar takes no anchors, since no single bar stands for the chart; a bar colored by its own category is not grouped.

dx/dy (pixel offsets) are also available under labels to nudge a label off its default position. To enable labels for all bar charts at theme level, set marks.bar.labels.visible: true in your theme YAML.


Conditional styling

style.conditional restyles a bar by the value in its own row, with no color: channel. It maps a column name to a list of rules. Each rule is one condition (eq, ne, lt, lte, gt, gte, between, in, is_null, or default) plus the part of the bar chart style it applies:

type: bar
x: region
y: profit
style:
  marks:
    bar:
      color: "#4c78a8"
  conditional:
    profit:
      - lt: 0
        marks:
          bar:
            color: "#c62828"
          text:
            font:
              color: "#c62828"
              weight: "700"

A rule can set only what varies per bar:

Field Sets
marks.bar.color The bar's fill
marks.bar.opacity The fill opacity
marks.bar.border.color, marks.bar.border.width The bar's outline
marks.text.font.color, marks.text.font.weight The bar's value label
axis_x.labels.font.color The category labels the rule matches (Conditional label colors)

Anything else, such as orientation or marks.bar.band_width, is refused.

  • Every matching rule applies, and where two set the same field the later one wins, so list the more specific rule last.
  • A default: true rule must be last and applies only when no other rule matched.
  • The column must be in the query result. Rules on two columns cannot set the same field, unless both are in a multi-y y: list.
  • On a multi-y chart a rule on a y: column styles only that column's series. A rule on any other column styles every series at that x.
  • On a stacked bar each segment is tested against its own row.
  • Rules style the base layer only, never layers:.
  • conditional is authored on the chart's own style; at style.charts.bar it is refused.

Pattern Fills

Series that hue cannot separate can also carry patterns: see Pattern fills.

Overlays (layers:)

Add a layers: list to a bar chart to overlay additional marks, a line trend, a scatter reference, or a second bar series on a separate y-axis. The base bar chart owns the x-axis, frame, title, legend, and sort. Each layer adds its own mark and legend entry.

charts:
  revenue_vs_target:
    type: bar
    x: month
    y: revenue
    query: monthly
    layers:
      - type: line
        y: target
        label: Target
        axis_y:
          position: right
        style:
          marks:
            line:
              stroke:
                width: 2

A layer on its own axis gets an independent scale; see Dual y-axis for why dbt Charts warns about it and what to use instead.

Layer fields:

Field Description
type Mark type: bar, line, area, or scatter
y Measure column for this layer
label Legend label (defaults to the column name)
color Data field for color encoding on this layer
query Override the base query for this layer's data
x X field for this layer (values extend the base x-scale)
axis_y {position: left|right} plus per-side scale/format
style Marks-only style patch, nested under the layer's mark family (for example, marks.line.stroke.width)

sort: and x-axis chrome are base-only; layers inherit x ordering.


Ribbons

A ribbon is a band that joins each bar, or each stacked segment, to the same series in the next category. It is drawn in a fainter shade of the series color, so it reads as a connection, not a mark. Ribbons suit bars whose categories are in order (stages, months), where the eye should follow each series from one bar to the next. They work on single-series bars and on every stack (zero, normalize, center); grouped bars refuse them.

type: bar
x: month
y: connections
color: stage
style:
  stack: normalize
  marks:
    bar:
      ribbons:
        visible: true

Funnels

type: funnel draws the stages of one process as centered bars, first to last, with ribbons joining each stage to the next and no value axis. The query supplies one row per stage in order. Each bar is labeled with what remains at that stage, and each ribbon with the percent lost since the stage before.

queries:
  stages:
    columns: [stage_order, stage, users]
    values:
      - [1, Visited, 4200]
      - [2, Signed up, 3100]
      - [3, Activated, 1900]
      - [4, Upgraded, 740]
charts:
  signup:
    type: funnel
    query: stages
    x: stage
    y: users
    sort:
      by: stage_order
rows:
  - signup

A label that doesn't fit inside its bar or ribbon sits just outside it. Bar labels print the column's own format, so a whole-number column prints whole numbers.

Label templates

style.marks.bar.labels.template and style.marks.bar.ribbons.labels.template rewrite the labels. A template names value, percent_of_first and percent_of_previous. On a bar, value is its count; on a ribbon, the change from the stage before, negative for a loss. The percents are that value as a share of the first stage or of the stage before; the first bar is 100% of itself. A second value goes in parentheses:

queries:
  stages:
    columns: [stage_order, stage, users]
    values:
      - [1, Visited, 4200]
      - [2, Signed up, 3100]
      - [3, Activated, 1900]
      - [4, Upgraded, 740]
charts:
  signup:
    type: funnel
    query: stages
    x: stage
    y: users
    sort:
      by: stage_order
    style:
      marks:
        bar:
          labels:
            template: "{{ value | format(',d') }} ({{ percent_of_first | format('.0%') }})"
          ribbons:
            labels:
              template: "{{ percent_of_previous | format('.0%') }} ({{ value | format(',d') }})"
rows:
  - signup

Because the second value sits in parentheses, a format that writes negatives in parentheses is refused in a template with two values.

Support table

A support_table: moves the numbers off the marks, and the bar and ribbon labels default to hidden. A percent: column shows each stage's share of the first stage. Stage values print in the same ink as the stage names. Between the stage rows, ribbon rows show the change from the stage before, in the theme's ribbon color: units in a column that reads the count, a percent in a percent: column.

queries:
  stages:
    columns: [stage_order, stage, users]
    values:
      - [1, Visited, 4200]
      - [2, Signed up, 3100]
      - [3, Activated, 1900]
      - [4, Upgraded, 740]
charts:
  signup:
    type: funnel
    query: stages
    x: stage
    y: users
    sort:
      by: stage_order
    support_table:
      - source: users
        label: Users
      - percent: users
        label: Share
rows:
  - signup

Styling every funnel

A funnel is a bar drawn by the theme's funnel recipe, style.charts.funnel, which sits over style.charts.bar the way style.charts.donut sits over style.charts.pie. A board's bar style reaches its funnels, its charts.funnel style restyles them alone, and a chart's own style: wins over both:

style:
  charts:
    funnel:
      marks:
        bar:
          band_width: 0.8
queries:
  stages:
    columns: [stage_order, stage, users]
    values:
      - [1, Visited, 4200]
      - [2, Signed up, 3100]
      - [3, Activated, 1900]
      - [4, Upgraded, 740]
charts:
  signup:
    type: funnel
    query: stages
    x: stage
    y: users
    sort:
      by: stage_order
rows:
  - signup

Limits

A chart's own style.stack and style.marks.bar.ribbons.visible override the recipe. A funnel's bars are always thicker than its ribbons, so a band_width of 0.5 or less is refused, and so is a vertical style.orientation (use type: bar with style.stack: center). Ribbon labels and percent: columns are for funnels only.

A centered funnel shows the WARN-BAR-CENTERED-NO-BASELINE warning, as every centered bar does: centered bars share no edge to measure from, so their lengths are hard to compare. When exact comparison matters, set style.stack: zero, so every bar starts at zero.