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.

Dataface bar charts use a small set of top-level shorthand fields together with style. By default, style.orientation is auto: Dataface picks vertical for time-series, numeric-bin, and short-label categorical bars, and horizontal for long-name categorical bars whose labels won't fit side-by-side horizontally. Set style.orientation: vertical or style.orientation: horizontal to lock in a specific orientation regardless of label length. 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 Dataface, 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 Single-Chart Property Catalog.

Minimum Required for a Bar Chart

These are the minimum fields required to render a basic bar chart in Dataface. The default result is a vertical bar chart, also known as a column chart.

Dataface 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 for column charts.
y encoding.y.field Field name Numeric measure to compare.

Minimum Example

charts:
  product_revenue_columns:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - product_revenue_columns
Gadget XGadget YTool ZWidget AWidget BProduct$0$5,000$10,000$15,000$20,000$25,000$30,000$35,000$40,000$45,000$50,000$55,000$60,000$65,000$70,000$75,000$80,000$85,000RevenueRevenue by Product 2026-05-12 12:35
▶

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.

Dataface 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.
description metadata String Available for tooling and docs.
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.
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: a default vertical bar chart, also called a column chart, and the same chart rendered horizontally.

charts:
  product_revenue_columns:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue

  product_revenue_bars:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
    style:
      orientation: horizontal
rows:
  - product_revenue_columns
  - product_revenue_bars
Gadget XGadget YTool ZWidget AWidget BProduct$0$5,000$10,000$15,000$20,000$25,000$30,000$35,000$40,000$45,000$50,000$55,000$60,000$65,000$70,000$75,000$80,000$85,000RevenueRevenue by Product010,00020,00030,00040,00050,00060,00070,00080,0005,00015,00025,00035,00045,00055,00065,00075,00085,000RevenueGadget XGadget YTool ZWidget AWidget BProductRevenue by Product 2026-05-12 12:35
▶

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.

charts:
  ranked_products:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: Top Products by Revenue
    description: A sorted product ranking shown as horizontal bars.
    x: product
    y: revenue
    x_label: Product
    y_label: Revenue
    format: "$,.0f"
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
rows:
  - ranked_products
010,00020,00030,00040,00050,00060,00070,00080,0005,00015,00025,00035,00045,00055,00065,00075,00085,000RevenueWidget BWidget ATool ZGadget YGadget XProductTop Products by Revenue 2026-05-12 12:35
▶

Layered Multi-Metric Bars

When y is a list, Dataface 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
Gadget XGadget YTool ZWidget AWidget BProduct$0$5,000$10,000$15,000$20,000$25,000$30,000$35,000$40,000$45,000$50,000$55,000$60,000$65,000$70,000$75,000$80,000$85,000Revenue, ProfitRevenue and Profit by Product 2026-05-12 12:35
▶

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 bar charts without changing the underlying data bindings.

charts:
  category_columns_styled:
    query: _doc_examples.yaml#sales_by_category
    type: bar
    title: Revenue by Category
    x: category
    y: revenue
    color: category
    style:
      legend:
        disable: true
      axis:
        grid:
          hidden: true
rows:
  - category_columns_styled
AccessoriesElectronicsToolsCategory$0$10,000$20,000$30,000$40,000$50,000$60,000$70,000$80,000$90,000$100,000$110,000$120,000$130,000$140,000$150,000RevenueRevenue by Category 2026-05-12 12:35
▶

Axis, Scale, and Orientation

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

Dataface field Maps to Vega-Lite Allowed values Notes
style.orientation bar orientation transform auto (default), vertical, or horizontal auto picks horizontal when x-axis labels don't fit; 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.scale config.scale ScaleStyle object Global scale config (zero, nice, domain, clamp).
style.stack encoding.y.stack true, false, "zero", "normalize", "center" Stacking behavior. false for grouped bars.

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.

charts:
  product_revenue_ranked:
    query: _doc_examples.yaml#sales_by_product
    type: bar
    title: Product Revenue Ranking
    x: product
    y: revenue
    sort:
      by: revenue
      order: desc
    style:
      orientation: horizontal
      axis_x:
        format: "$,.0f"
      axis_y:
        label:
          limit: 140
      scale:
        nice: true
rows:
  - product_revenue_ranked
010,00020,00030,00040,00050,00060,00070,00080,00090,0005,00015,00025,00035,00045,00055,00065,00075,00085,000Revenue$NaN$NaN$NaN$NaN$NaNProductProduct Revenue Ranking 2026-05-12 12:35
▶

Endpoint Labels and the Top-Row Series Rail

Set style.bar.endpoint_labels.enabled: true to move the series names off the side legend and onto the chart, anchored to each segment. 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 rightmost column. 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.

Dataface field Allowed values Notes
style.bar.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 or rail is on, the categorical legend turns off automatically — the two would encode the same series→colour mapping twice. On the vertical layout, the y-axis also auto-flips to the left so it doesn't collide with the right-edge label pane.

When neighboring labels in the horizontal rail would overlap, the resolver lifts the right-hand label by one line-height (vertical dodge). The leftmost label always sits at the base row — that determinism is part of the contract. Dodging caps at three rows above base; if all three rows still collide, the resolver accepts overlap deterministically rather than dropping a label silently.

The endpoint-labels primitive does not fire on grouped horizontal bars (stack: false), since grouped bars don't form stacks to label. It also stays off for single-series charts (no color encoding) where there are no segments to name.

Vertical Stacked Columns

charts:
  product_revenue_by_category_vertical:
    query: _doc_examples.yaml#sales_product_category
    type: bar
    title: Revenue by Product (vertical stack)
    x: product
    y: revenue
    color: category
    style:
      bar:
        endpoint_labels:
          enabled: true

rows:
  - product_revenue_by_category_vertical
Gadget XGadget YTool ZWidget AWidget BProduct$0$5,000$10,000$15,000$20,000$25,000$30,000$35,000$40,000$45,000$50,000$55,000$60,000$65,000$70,000$75,000$80,000$85,000$90,000RevenueRevenue by Product (vertical stack)Electronics 2026-05-12 12:35
▶

Horizontal Stacked Bars

charts:
  product_revenue_by_category:
    query: _doc_examples.yaml#sales_product_category
    type: bar
    title: Revenue by Product (stacked by Category)
    x: product
    y: revenue
    color: category
    style:
      orientation: horizontal
      bar:
        endpoint_labels:
          enabled: true

rows:
  - product_revenue_by_category
Accessories05,00010,00015,00020,00025,00030,00035,00040,00045,00050,00055,00060,00065,00070,00075,00080,00085,00090,000RevenueGadget XGadget YTool ZWidget AWidget BProductRevenue by Product (stacked by Category) 2026-05-12 12:35
▶

Advanced Vega-Lite Escape Hatches

Dataface bar charts are authored with type: bar plus top-level fields such as x, y, color, sort, and style. When you need deeper Vega-Lite customization, use top-level config, transform, params, resolve, hconcat, vconcat, concat, or repeat.