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. The most important difference from line graphs is that color often creates stacked filled bands, so 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 Single-Chart Property Catalog.

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
Jan2026FebWeek020406080100120140160180200220240260SignupsWeekly Signups 2026-05-12 12:34
▶

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 Usually creates stacked area bands for grouped series.
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 to split one area chart into stacked category bands so readers can see both total volume and changing composition over time.

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
rows:
  - stacked_area
Jan2026FebMarAprMayMonth0102030405060708090100110120130140150160SignupsOrganicPaidPartnerchannelSignup Mix by Channel 2026-05-12 12:34
▶

Streamgraph Baseline

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

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
rows:
  - listening_streamgraph
Jan2026FebMarAprMayJunMonth05101520253035404550556065ListenersAmbientIndieJazzgenreListening Mix by Genre 2026-05-12 12:34
▶

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
    format: "$,.0f"
    style:
      legend:
        disable: true
      axis:
        grid:
          hidden: true
      scale:
        zero: false
rows:
  - revenue_area
Jan2026FebMarAprMayJunMonth$420,000$430,000$440,000$450,000$460,000$470,000$480,000$490,000$500,000$510,000$520,000$530,000$540,000$550,000$560,000$570,000$580,000$590,000$600,000RevenueMonthly Revenue 2026-05-12 12:34
▶

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
Jan2026FebMarAprMayJunMonth$0$100,000$200,000$300,000$400,000$500,000$600,000$50,000$150,000$250,000$350,000$450,000$550,000Actual Revenue, Forecast RevenueActual RevenueForecast RevenueActual vs Forecast Revenue 2026-05-12 12:34
▶

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.disable encoding.color.legend true or false Typed legend control. true hides the legend.
style.axis.grid axis grid flags true or false Typed grid visibility control.
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
    format: "$,.0f"
    style:
      legend:
        disable: true
      axis:
        grid:
          hidden: true
      scale:
        zero: false
rows:
  - revenue_area
Jan2026FebMarAprMayJunMonth$420,000$430,000$440,000$450,000$460,000$470,000$480,000$490,000$500,000$510,000$520,000$530,000$540,000$550,000$560,000$570,000$580,000$590,000$600,000RevenueMonthly Revenue 2026-05-12 12:34
▶

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
    format: "$,.0f"
    style:
      legend:
        disable: true
      axis:
        grid:
          hidden: true
      scale:
        zero: false
rows:
  - revenue_area
Jan2026FebMarAprMayJunMonth$420,000$430,000$440,000$450,000$460,000$470,000$480,000$490,000$500,000$510,000$520,000$530,000$540,000$550,000$560,000$570,000$580,000$590,000$600,000RevenueMonthly Revenue 2026-05-12 12:34
▶

Endpoint Labels

Set style.area.endpoint_labels.enabled: 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.area.endpoint_labels.enabled 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:
      area:
        endpoint_labels:
          enabled: true

rows:
  - stacked_area_with_endpoint_labels
Jan2026FebMarAprMayMonth0102030405060708090100110120130140150160SignupsSignup Mix by ChannelOrganicPaidPartner 2026-05-12 12:34
▶

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.