Line Graphs¶

Line graphs connect values across an ordered axis, usually time, to emphasize continuity, direction, rate of change, and overall shape; this family includes single- or multi-series lines and slope graphs. They are most useful when the main question is how something changes over time rather than how big isolated categories are.

Dataface line graphs use a small set of top-level shorthand fields together with style. In most cases, you only need query, type: line, x, and y to get started.

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 a Line Graph¶

These are the minimum fields required to render a basic line graph in Dataface.

Dataface field	Maps to Vega-Lite	Allowed values	Notes
`query`	`data.values`	Query name or query reference	Supplies the dataset.
`type: line`	`mark.type: "line"`	Literal `line`	Selects the line mark.
`x`	`encoding.x.field`	Field name	Ordered dimension, usually time.
`y`	`encoding.y.field`	Field name	Numeric measure to plot.

Minimum Example¶

charts:
  revenue_trend_minimal:
    query: _doc_examples.yaml#sales_by_date
    type: line
    title: Daily Revenue
    x: date
    y: revenue
rows:
  - revenue_trend_minimal

▶

Top-Level Chart Fields¶

These are the top-level chart properties you set directly on a line graph 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: line`	`mark.type: "line"`	Literal `line`	Selects the line 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 lines.
`title`	`title.text`	String	Chart title.
`description`	metadata	String	Available for tooling and docs.
`color`	`encoding.color.field`	Field name	Groups a line into multiple 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.

Multi-Series Line Graph¶

This example adds color to split one line into multiple series while keeping the top-level chart definition compact.

charts:
  revenue_by_product:
    query: _doc_examples.yaml#sales_by_date_product
    type: line
    title: Revenue by Product
    x: date
    y: revenue
    color: product
rows:
  - revenue_by_product

▶

Axis Labels, Formatting, and Styling¶

This example shows common top-level chart fields such as labels and numeric formatting.

charts:
  revenue_formatted:
    query: _doc_examples.yaml#sales_by_date
    type: line
    title: Revenue Over Time
    x: date
    y: revenue
    x_label: Date
    y_label: Revenue
    format: "$,.0f"
    style:
      scale:
        zero: false
      axis:
        grid:
          hidden: true
rows:
  - revenue_formatted

▶

Layered Multi-Metric Lines¶

When y is a list, Dataface creates a layered line graph. This is useful when you want to compare two measures that share the same ordered x-axis.

charts:
  revenue_and_units:
    query: _doc_examples.yaml#sales_by_date
    type: line
    title: Revenue And Units Sold
    x: date
    y: [revenue, units_sold]
rows:
  - revenue_and_units

▶

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 shows the small style surface for line graphs without changing the underlying data bindings.

charts:
  revenue_formatted:
    query: _doc_examples.yaml#sales_by_date
    type: line
    title: Revenue Over Time
    x: date
    y: revenue
    x_label: Date
    y_label: Revenue
    format: "$,.0f"
    style:
      scale:
        zero: false
      axis:
        grid:
          hidden: true
rows:
  - revenue_formatted

▶

Axis and Scale Style¶

Use style for axis and scale properties that shape how the line graph 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).

Axis and Scale Controls¶

This example uses style to control the y-axis scale and tick density.

charts:
  revenue_formatted:
    query: _doc_examples.yaml#sales_by_date
    type: line
    title: Revenue Over Time
    x: date
    y: revenue
    x_label: Date
    y_label: Revenue
    format: "$,.0f"
    style:
      scale:
        zero: false
      axis:
        grid:
          hidden: true
rows:
  - revenue_formatted

▶

Endpoint Labels¶

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

Dataface field	Allowed values	Notes
`style.line.endpoint_labels.enabled`	`true` or `false`	Opt-in feature toggle. Defaults to `false` on the standard theme, `true` on editorial themes.

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 lines there's only one series to name, so the feature is a no-op.

charts:
  revenue_by_product:
    query: _doc_examples.yaml#sales_by_date_product
    type: line
    title: Revenue by Product
    x: date
    y: revenue
    color: product
    style:
      line:
        endpoint_labels:
          enabled: true

rows:
  - revenue_by_product

▶

Authored Surface¶

Dataface line charts are authored with type: line 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.