Charts¶

Charts visualize your query data. Each chart references a query and defines how to display it.

Vega-Lite foundation: Charts are rendered using Vega-Lite. All Vega-Lite chart types are supported and passed through directly. See the Chart Types for a complete list.

Basic Chart Structure¶

charts:
  revenue_chart:
    title: "Revenue by Month"
    query: queries.sales          # References a query name
    type: bar                     # Chart type
    x: month                      # X-axis dimension
    y: total_revenue              # Y-axis metric

Here's a working example:

charts:
  revenue_chart:
    query: _doc_examples.yaml#sales
    type: bar
    title: Revenue by Product
    x: product
    y: revenue
rows:
  - revenue_chart

▶

Common Chart Types¶

Type	Best For
`line`	Time series trends
`bar`	Comparisons across categories
`area`	Stacked trends over time
`scatter`	Relationships between metrics
`pie` / `donut`	Part-to-whole comparisons
`heatmap`	Two-dimensional patterns
`histogram`	Distributions
`table`	Detailed data view
`kpi`	Single metric display

See also: Chart Types for common types with examples • More Types for all Vega-Lite marks

Field Reference¶

charts:
  <chart_id>:              # Unique identifier (must be unique within a file and across all imported files)
    title: string          # Optional
    query: string          # Required
    type: string           # Required (bar, line, area, etc.)

    # Axis/encoding fields
    x: string              # Dimension for x-axis
    y: string | [string]   # Metric(s) for y-axis
    color: string          # Field to encode as color
    size: string           # Field to encode as size
    shape: string          # Field to encode as shape

    # Data transformation
    group_by: [string]     # Client-side grouping
    sort:
      by: string
      order: asc | desc
    limit: number          # Max rows to show

    # KPI-specific
    metric: string         # Required for KPI type

    # Styling
    style:
      palette: string      # Color scheme name
      legend: show | hide
      grid_lines: boolean
      labels: auto | show | hide

    # Interactions (click not yet implemented)
    interactions:
      click:                     # Coming soon
        action: drill | filter | link | set_variable
        target: string | [string]
        value_map:
          field: string
          format: string
      hover:
        tooltip: boolean         # Works automatically

    # Filtering
    filters:
      <field>: <expression>

    description: string    # Help text/tooltip

Chart Styling¶

Customize chart appearance:

charts:
  styled_chart:
    query: queries.sales
    type: bar
    x: month
    y: total_revenue
    style:
      palette: "category10"       # Color scheme
      legend: show                # Show legend
      grid_lines: true            # Show grid lines
      labels: auto                # Auto-label placement

Style options: - palette: Color scheme (e.g., "category10", "viridis", "blues") - legend: show or hide the legend - grid_lines: true or false - labels: auto, show, or hide axis labels

See the Styling guide for themes and color palettes.

Best Practices¶

Choosing Chart Types¶

Time series: Use line or area
Comparisons: Use bar
Relationships: Use scatter
Single numbers: Use kpi
Detailed data: Use table

Effective Color Encoding¶

Use color to distinguish categories
Choose accessible palettes (colorblind-friendly)
Limit distinct colors (5-7 max)

Filtering¶

Use variables with dropdowns for cross-chart filtering
Tooltips appear automatically on hover

See Interactions for details. Click interactions are planned for a future release.

Previewing Charts¶

Preview your charts interactively:

face serve dashboards/sales.yml --reload

The --reload flag auto-refreshes on save. See CLI Reference.

Validate First¶

face validate dashboards/sales.yml

Chart Types - Common charts with examples
More Types - All Vega-Lite marks and reference tables
Interactions - Hover behaviors (click interactions coming soon)
Queries - Data sources for charts
Boards - Organizing charts in dashboards
Variables - Variables in interactions
Styling - Themes and color palettes