Skip to content

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.

Dataface 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 Dataface, 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 Dataface.

Dataface 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
Dataface Jan2026Feb150200250Weekly Signups 2026-07-17 15:04 UTC made with dataface
▶

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.

Dataface 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 creates layered multi-metric areas.
title title.text String Chart title.
description metadata String Available for tooling and docs.
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.
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
Dataface Jan2026FebMarAprMay050100150Signup Mix by ChannelOrganicPaidPartner 2026-07-17 15:04 UTC made with dataface
▶

Stacked Area Recipe

When style.stack is non-false ("zero", true, "normalize", or "center"), Dataface 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

Streamgraph Baseline

This example uses style.stack: center to shift a stacked area chart to a centered baseline, producing a streamgraph-style view.

The editorial theme enables endpoint labels for area charts by default, but endpoint labels are not compatible with centered-baseline stacks (the diverging domain makes anchor computation undefined). Set endpoint_labels.visible: false explicitly on streamgraph charts and use legend.visible: true to restore series identification.

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
      legend:
        visible: true
      endpoint_labels:
        visible: false
rows:
  - listening_streamgraph
Dataface Jan2026FebMarAprMayJun3040506070AmbientIndieJazzgenreListening Mix by Genre 2026-07-17 15:04 UTC made with dataface
▶

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.

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:
      number_format: currency_whole
      legend:
        visible: false
      axis:
        grid:
          visible: false
      scale:
        zero: false
rows:
  - revenue_area
Dataface Jan2026FebMarAprMayJunMonth$450,000$500,000$550,000$600,000RevenueMonthly Revenue 2026-07-17 15:04 UTC made with dataface
▶

Layered Multi-Metric Areas

When y is a list, Dataface creates layered area charts. 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 layered lines.

queries:
  revenue_and_forecast:
    columns: [month, actual_revenue, forecast_revenue]
    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_revenue, forecast_revenue]
rows:
  - layered_areas
Dataface Jan2026FebMarAprMayJun400k420k440k460k480k500k520k540k560k580k600kactual revenueforecast revenueActual vs Forecast Revenue 2026-07-17 15:04 UTC made with dataface
▶

Style Fields

Use style for Dataface shorthand properties that affect presentational defaults such as legend visibility and grid lines.

Dataface 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 grid lines. 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 Grid Lines

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:
      number_format: currency_whole
      legend:
        visible: false
      axis:
        grid:
          visible: false
      scale:
        zero: false
rows:
  - revenue_area
Dataface Jan2026FebMarAprMayJunMonth$450,000$500,000$550,000$600,000RevenueMonthly Revenue 2026-07-17 15:04 UTC made with dataface
▶

Axis and Scale Style

Use style for axis and scale properties that shape how the area chart is framed and read.

Dataface 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.scale config.scale ScaleStyle object Global scale config (zero, nice, domain, clamp).
style.stack encoding.y.stack true, false, "zero", "normalize", "center" Stacking behavior. "center" for streamgraphs.

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:
      number_format: currency_whole
      legend:
        visible: false
      axis:
        grid:
          visible: false
      scale:
        zero: false
rows:
  - revenue_area
Dataface Jan2026FebMarAprMayJunMonth$450,000$500,000$550,000$600,000RevenueMonthly Revenue 2026-07-17 15:04 UTC made with dataface
▶

Endpoint Labels

Set style.endpoint_labels.visible: true on a multi-series area chart to move the series names off the side legend and onto the chart, anchored to each band's final value. The chart pane and label pane sit side-by-side in an hconcat, with one label per series.

Dataface field Allowed values Notes
style.endpoint_labels.visible true or false Opt-in feature toggle. Defaults to false.

When the label pane is on, the categorical legend turns off automatically — the two would encode the same series→colour mapping twice. The y-axis also auto-flips to the left so it doesn't collide with the right-edge label pane.

Endpoint labels require a color channel (a multi-series chart); on single-series areas there's only one series to name, so the feature is a no-op.

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:
      endpoint_labels:
        visible: true

rows:
  - stacked_area_with_endpoint_labels
Dataface Jan2026FebMarAprMay050100150Signup Mix by ChannelOrganicPaidPartner 2026-07-17 15:04 UTC made with dataface
▶

Authored Surface

Dataface 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 Dataface fields and the typed style: object.