Area Charts¶
Area charts show magnitude with filled shapes, usually under a line or across stacked layers, so they emphasize both trend and accumulated bands; this family includes simple area charts, stacked area charts, and streamgraph-style variants. They are most useful when you want viewers to see changing totals or composition over time, though they trade away some comparison precision compared with line graphs and bar charts.
dbt Charts area charts use a small set of top-level shorthand fields together with style. In most cases, you only need query, type: area, x, and y to get started. Adding color creates overlapping semi-transparent series by default; use style.stack: "zero" (or true) to switch to stacked bands. Area charts are especially useful when total accumulation or composition carries meaning.
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 typed style objects.
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 an Area Chart¶
These are the minimum fields required to render a basic area chart in dbt Charts.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
query |
data.values |
Query name or query reference | Supplies the dataset. |
type: area |
mark.type: "area" |
Literal area |
Selects the area mark. |
x |
encoding.x.field |
Field name | Ordered dimension, usually time. |
y |
encoding.y.field |
Field name | Numeric measure to plot as filled magnitude. |
Minimum Example¶
queries:
weekly_signups:
columns: [week, signups]
values:
- ["2026-01-05", 120]
- ["2026-01-12", 165]
- ["2026-01-19", 150]
- ["2026-01-26", 205]
- ["2026-02-02", 230]
- ["2026-02-09", 260]
charts:
signup_area:
query: weekly_signups
type: area
title: Weekly Signups
x: week
y: signups
rows:
- signup_area
Top-Level Chart Fields¶
These are the top-level chart properties you set directly on an area 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. |
type: area |
mark.type: "area" |
Literal area |
Selects the area mark. |
x |
encoding.x.field |
Field name | Usually a temporal or ordered field. |
y |
encoding.y.field |
Field name or list of field names | A list draws one area per measure on a shared y-axis. |
title |
title.text |
String | Chart title. |
notes |
metadata | String | AI search/context metadata. Never rendered. |
color |
encoding.color.field |
Field name | Creates overlapping area series by default; combine with style.stack: "zero" to stack bands. |
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 |
encoding.y.format and encoding.y.axis.format |
Format string | Numeric formatting for the y channel. |
sort |
categorical axis sort | Sort object | Most useful when the x-axis is categorical. |
projection |
top-level projection |
Vega-Lite projection name | Available for Vega-Lite projection overrides. |
Stacked Composition over Time¶
This example uses color plus style.stack: "zero" to split one area chart into stacked category bands so readers can see both total volume and changing composition over time. Without style.stack, the series overlap as semi-transparent silhouettes instead.
queries:
channel_mix:
columns: [month, channel, signups]
values:
- ["2026-01-01", "Organic", 90]
- ["2026-01-01", "Paid", 40]
- ["2026-01-01", "Partner", 18]
- ["2026-02-01", "Organic", 105]
- ["2026-02-01", "Paid", 48]
- ["2026-02-01", "Partner", 22]
- ["2026-03-01", "Organic", 118]
- ["2026-03-01", "Paid", 52]
- ["2026-03-01", "Partner", 29]
- ["2026-04-01", "Organic", 134]
- ["2026-04-01", "Paid", 58]
- ["2026-04-01", "Partner", 34]
- ["2026-05-01", "Organic", 146]
- ["2026-05-01", "Paid", 63]
- ["2026-05-01", "Partner", 38]
charts:
stacked_area:
query: channel_mix
type: area
title: Signup Mix by Channel
x: month
y: signups
color: channel
style:
stack: "zero"
rows:
- stacked_area
Stacked Area Recipe¶
When style.stack is non-false ("zero", true, "normalize", or "center"), dbt Charts automatically applies the stacked recipe: solid fills (opacity 1.0) with a 1-pixel background-color perimeter stroke separating adjacent bands. This is the same idiom as the stacked-bar border knockout: the separator is the chart background bleeding through the stroke, not a separately painted line, so it reads correctly on any background color.
The default overlap recipe (translucent fill + halo) is suppressed for stacked charts because bands in a stack never cross, so the halo undercoat provides no benefit.
Theme authors can override the stacked recipe via style.charts.marks.area.stacked:
style: charts: marks: area: stacked: opacity: 1.0 stroke: color: theme.background width: 1.5 halo_multiplier: 0.0
A single-series area also takes this recipe in full, even with style.stack left at its default "none". A chart counts as single-series when it has no color, no layers:, and no y: list of two or more measures. With one band there is nothing to overlap and nothing for a trend line to sit on top of, so a single-series area gets the same solid fill, background-color separator stroke, and halo turned off as a real stacked chart.
This means style.charts.marks.area.opacity and style.charts.marks.line.stroke, which configure the multi-series overlap recipe's fill and top-edge trend line, are ignored on a single-series area. Use style.charts.marks.area.stacked.opacity to set its fill opacity and style.charts.marks.area.stacked.stroke to style its edge.
Streamgraph Baseline¶
This example uses style.stack: center to shift a stacked area chart to a centered baseline, producing a streamgraph-style view.
Endpoint labels work on a centered baseline: each label anchors to its band's midpoint at the final x position, so the series names sit on the bands instead of in a side legend. That matters more here than on most charts: streamgraph bands share no common baseline, so a legend forces the reader to match colors across the page.
queries:
listening_mix:
columns: [month, genre, listeners]
values:
- ["2026-01-01", "Ambient", 42]
- ["2026-01-01", "Indie", 58]
- ["2026-01-01", "Jazz", 33]
- ["2026-02-01", "Ambient", 48]
- ["2026-02-01", "Indie", 62]
- ["2026-02-01", "Jazz", 36]
- ["2026-03-01", "Ambient", 54]
- ["2026-03-01", "Indie", 59]
- ["2026-03-01", "Jazz", 41]
- ["2026-04-01", "Ambient", 61]
- ["2026-04-01", "Indie", 55]
- ["2026-04-01", "Jazz", 45]
- ["2026-05-01", "Ambient", 57]
- ["2026-05-01", "Indie", 51]
- ["2026-05-01", "Jazz", 49]
- ["2026-06-01", "Ambient", 50]
- ["2026-06-01", "Indie", 46]
- ["2026-06-01", "Jazz", 53]
charts:
listening_streamgraph:
query: listening_mix
type: area
title: Listening Mix by Genre
x: month
y: listeners
color: genre
style:
stack: center
rows:
- listening_streamgraph
Labels, Formatting, and Style¶
This example shows common top-level chart fields such as labels and numeric formatting, and it also serves as the shared example for basic style and axis-setting controls. An area with zero: false warns that its fill is cropped; warnings_ignore silences the warning.
queries:
monthly_revenue:
columns: [month, revenue]
values:
- ["2026-01-01", 420000]
- ["2026-02-01", 455000]
- ["2026-03-01", 480000]
- ["2026-04-01", 510000]
- ["2026-05-01", 548000]
- ["2026-06-01", 592000]
charts:
revenue_area:
query: monthly_revenue
type: area
title: Monthly Revenue
x: month
y: revenue
x_label: Month
y_label: Revenue
style:
legend:
visible: false
axis:
grid:
visible: false
axis_y:
scale:
continuous:
zero: false
labels:
format: currency_whole
rows:
- revenue_area
Multi-Metric Areas¶
When y is a list, dbt Charts draws one area per measure on a shared y-axis. This is useful when you want to compare two measures on the same x-axis, though overlap usually makes this a less precise choice than multi-metric lines.
queries:
revenue_and_forecast:
columns: [month, actual, forecast]
values:
- ["2026-01-01", 420000, 405000]
- ["2026-02-01", 455000, 438000]
- ["2026-03-01", 480000, 470000]
- ["2026-04-01", 510000, 500000]
- ["2026-05-01", 548000, 540000]
- ["2026-06-01", 592000, 575000]
charts:
layered_areas:
query: revenue_and_forecast
type: area
title: Actual vs Forecast Revenue
x: month
y: [actual, forecast]
rows:
- layered_areas
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. |
style.marks.area.curve |
area interpolation | linear (default), monotone, step |
Same interpolation options as line graphs; see Smoothing & Step Lines. No connect option on area (unlike line): a disconnected step area is just a bar chart via the wrong primitive. |
Legend and Gridlines¶
This example reuses the labels-and-formatting chart so you can see the style changes without introducing a second dataset.
queries:
monthly_revenue:
columns: [month, revenue]
values:
- ["2026-01-01", 420000]
- ["2026-02-01", 455000]
- ["2026-03-01", 480000]
- ["2026-04-01", 510000]
- ["2026-05-01", 548000]
- ["2026-06-01", 592000]
charts:
revenue_area:
query: monthly_revenue
type: area
title: Monthly Revenue
x: month
y: revenue
x_label: Month
y_label: Revenue
style:
legend:
visible: false
axis:
grid:
visible: false
axis_y:
scale:
continuous:
zero: false
labels:
format: currency_whole
rows:
- revenue_area
Axis and Scale Style¶
Use style for axis and scale properties that shape how the area chart is framed and read.
| dbt Charts field | Maps to Vega-Lite | Allowed values | Notes |
|---|---|---|---|
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). |
style.stack |
encoding.y.stack |
true, false, "zero", "normalize", "center" |
Stacking behavior. "center" for streamgraphs. |
style.stack_order |
encoding.order |
"value" (default), "data", "alphabetical" |
Band order from the baseline up. "value" puts the largest total 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. |
Axis and Scale Controls¶
This example reuses the labels-and-formatting chart so the effect of style stays easy to isolate.
queries:
monthly_revenue:
columns: [month, revenue]
values:
- ["2026-01-01", 420000]
- ["2026-02-01", 455000]
- ["2026-03-01", 480000]
- ["2026-04-01", 510000]
- ["2026-05-01", 548000]
- ["2026-06-01", 592000]
charts:
revenue_area:
query: monthly_revenue
type: area
title: Monthly Revenue
x: month
y: revenue
x_label: Month
y_label: Revenue
style:
legend:
visible: false
axis:
grid:
visible: false
axis_y:
scale:
continuous:
zero: false
labels:
format: currency_whole
rows:
- revenue_area
Endpoint Labels¶
A multi-series area chart names its series on the chart, anchored to each band's final value, rather than in a side legend. An unstacked area's label reads the series' final 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 area (style.stack: zero, normalize or center) labels the name alone, because a band's midpoint is not the series' value. This is the default on every built-in theme; you don't switch it on. Set style.legend.position.edge to a side (top, bottom, left, right) to send the names back to a legend.
| 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 names its series on the chart when it has more than one, and steps aside to a legend where a rail would not fit (for example a single series, a multiples: chart, a layered chart with a single base series, or a chart too narrow for the rail). A side keeps a legend there and prints no endpoint labels, at the chart, board or project (meta.yml) level; endpoints forces the labels on wherever a rail can render (multiples: charts refuse it). 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 labels.
When the label pane 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. The y-axis also auto-flips to the left so it doesn't collide with the right-edge label pane.
On narrow cards, endpoint-label text compacts to fit the available width while its automatic vertical spacing stays readable for closely ending series.
Endpoint labels require a multi-series chart: either a color channel or a y: [field_a, field_b] list. On single-series areas there is only one series to name, so the feature is a no-op.
y: [...] composes with a color: column: the measures are crossed with the column's values, one series per value per measure, each named <value> - <measure> (see Multiple Measures by a Dimension). layers: overlay a y: [...] chart too: each layer takes the next free color after the folded series.
queries:
channel_mix:
columns: [month, channel, signups]
values:
- ["2026-01-01", "Organic", 90]
- ["2026-01-01", "Paid", 40]
- ["2026-01-01", "Partner", 18]
- ["2026-02-01", "Organic", 105]
- ["2026-02-01", "Paid", 48]
- ["2026-02-01", "Partner", 22]
- ["2026-03-01", "Organic", 118]
- ["2026-03-01", "Paid", 52]
- ["2026-03-01", "Partner", 29]
- ["2026-04-01", "Organic", 134]
- ["2026-04-01", "Paid", 58]
- ["2026-04-01", "Partner", 34]
- ["2026-05-01", "Organic", 146]
- ["2026-05-01", "Paid", 63]
- ["2026-05-01", "Partner", 38]
charts:
stacked_area_with_endpoint_labels:
query: channel_mix
type: area
title: Signup Mix by Channel
x: month
y: signups
color: channel
style:
legend:
position:
edge: endpoints
rows:
- stacked_area_with_endpoint_labels
Pattern Fills¶
Series that hue cannot separate can also carry patterns: see Pattern fills.
Overlays (layers:)¶
Add a layers: list to an area chart to overlay additional marks, a line for a
reference trend, a scatter for individual points, or a second series on a separate
y-axis. The base area chart owns the x-axis, frame, title, legend, and sort. Each layer
contributes its own mark and legend entry.
charts: revenue_with_forecast_line: type: area x: month y: revenue query: monthly style: stack: "zero" layers: - type: line y: forecast label: Forecast style: marks: line: stroke: width: 2 dasharray: "4 2"
Layer fields: type, y, label, color, query, x, axis_y, style (marks-only patch). sort: is base-only; layer x-values extend the base x-scale.
Stacking a y: List in Listed Order¶
Stacked bands default to the largest total at the baseline. Set style.stack_order: data to stack a y: list in the order you wrote it: here subscriptions sits at the baseline even though services is larger.
queries:
revenue_by_line:
columns: [month, subscriptions, services, hardware]
values:
- ["2026-01-01", 40000, 90000, 15000]
- ["2026-02-01", 46000, 92000, 14000]
- ["2026-03-01", 53000, 95000, 16000]
charts:
listed_order_areas:
query: revenue_by_line
type: area
x: month
y: [subscriptions, services, hardware]
style:
stack: zero
stack_order: data
rows:
- listed_order_areas
Conditional styling¶
style.conditional restyles the points and area fill by the value in its own row, so a presentation choice stays out of the query. 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 area chart style it applies:
type: area x: month y: revenue style: marks: point: size: 60 conditional: is_forecast: - eq: true marks: point: opacity: 0.4
A rule can set only what varies along the series:
| Field | Sets |
|---|---|
marks.point.color, marks.point.fill, marks.point.filled |
The point's paint; fill applies when filled: false |
marks.point.size, marks.point.shape |
The point's size and symbol |
marks.point.opacity, marks.point.stroke_width |
The point's opacity and ring width |
marks.area.color, marks.area.opacity |
The area fill between matching points |
marks.line.stroke.color, marks.line.stroke.width, marks.line.stroke.dasharray |
The top edge between matching points |
axis_x.labels.font.color |
The x-axis labels the rule matches (Conditional label colors) |
curve, stacked, backdrop, marks.line.{cap, join, labels, halo_multiplier} and marks.rule describe the whole series, so they are not conditionable and a rule that sets one is refused (for example marks: {area: {curve: step}}).
Restyling the fill and the top edge¶
The fill and the top edge are drawn between points, so a segment takes a rule's marks.area and marks.line style only when both of its end points match the rule. A run of matching points restyles the fill and edge under them, a single matching point restyles nothing, the two keys are independent, and the segment that steps into the run keeps the base style. Where two end points resolve different values for a key, the base style is used for that key. Stacked areas are cut the same way, band by band: the top edge of a band is stroked apart from the rest of its perimeter.
The curve is computed over the whole series and then cut at the points, so the restyled fill has the shape of the plain one. A basis curve, a step curve over a category axis, a stacked area with link: and a color on a patterned fill (pattern:) cannot be cut and are refused.
To shade a forecast starting at the last actual month, make the boundary point match too. Have the query compute a column that is true from the last actual month on:
type: area x: month y: revenue style: conditional: from_last_actual: - eq: true marks: area: color: "#8a8a8a" opacity: 0.3
- Each point is tested against its own row, so on a multi-series chart a rule on
teamoris_forecaststyles that series' points individually. - A rule's
sizeoverrides the chart's point size at the matching rows:size: 0hides a point, and a positive size draws one where the chart'smarks.point.sizeis 0. - Every matching rule applies, and where two set the same field the later one wins, so list the more specific rule last.
- A
default: truerule 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. - Rules style the base layer only, never
layers:. conditionalis authored on the chart's ownstyle; atstyle.charts.areait is refused.
Authored Surface¶
dbt Charts area charts are authored with type: area plus top-level channels such as x, y, and color. Arbitrary Vega-Lite spec, mark, encoding, config, transform, params, and composition blocks are rejected on the authored surface. Use top-level dbt Charts fields and the typed style: object.