ChartML

Appearance

ChartML v1.0 Examples ​

Comprehensive examples demonstrating all ChartML v1.0 features including reusable sources, interactive parameters, chart types, and data aggregations. All examples in this file are validated against the JSON schema.

Related Documents:

Reusable Styles and Configuration ​

This section demonstrates how to define reusable themes and apply them across multiple charts.

Define a Reusable Style ​

yaml
type: style
version: 1
name: corporate_theme
colors: ["#4285f4", "#ea4335", "#fbbc04", "#34a853"]
grid:
  y: true
  color: "#e0e0e0"
  opacity: 0.5
height: 400
fonts:
  title:
    family: "Inter, sans-serif"
    size: 18
    weight: 600

Set Dashboard-Level Default Style ​

All charts below will inherit corporate_theme automatically:

yaml
type: config
version: 1
style: corporate_theme

Charts Automatically Inherit the Theme ​

Chart 1: Revenue Trend - Uses all defaults from corporate_theme

Chart 2: Customer Growth - Also inherits theme, demonstrates multiple charts sharing style

Chart with Selective Overrides (Deep Merge) ​

This chart overrides just height and grid color while keeping corporate_theme's fonts and base colors:

Config with Inline Style ​

For one-off dashboard themes without creating a named style, you can define inline styles:

yaml
type: config
version: 1
style:
  colors: ["#1a237e", "#3949ab", "#5e92f3"]
  height: 500
  grid:
    y: true
    color: "#f0f0f0"

(Note: Example shown as YAML instead of chartml to avoid multiple configs in this file)

KPI Overview: Executive Metrics Dashboard ​

This dashboard demonstrates metric cards (KPI cards) that display key performance indicators with trend comparisons.

Key Performance Metrics ​

A row of 4 metric cards showing critical business metrics with month-over-month comparisons:

Error Rate Metric (Inverted Trend) ​

This metric shows error rate where a decrease is positive (green) and an increase is negative (red).

Metric Label Rules:

Metric cards support two optional label locations:

  • chart.title → Label shown above the card (like all chart types)
  • visualize.label → Label shown inside the card (metric-specific feature)
  • If neither specified → Only the formatted value is shown

Examples:

Error Rate Example (inverted trend):

Reference Lines & Bands: Goal Tracking Dashboard ​

This dashboard demonstrates reference lines (goal markers) and bands (target ranges) for tracking performance against targets.

Monthly Revenue with Goal Line ​

Shows actual revenue with a goal line at $150,000:

Revenue Trend with Target Range ​

Shows revenue trend with a target range band:

Combo Chart: Actual vs Target with Stretch Goal ​

Shows actual revenue (bars) vs target (line) with both target band and stretch goal line:

Event Marker: Product Launch Impact ​

Shows daily sales with a vertical line marking a product launch date:

Dashboard 1: Q1 2025 Sales Performance ​

This executive dashboard shows sales metrics across regions and products for the first quarter of 2025.

Reusable Source: Q1 Sales Data ​

We'll define a shared source that multiple charts can reference:

Monthly Revenue Trend ​

Total revenue increased steadily throughout Q1, from $125k in January to $152k in March.

Revenue Distribution by Region ​

The North region consistently outperformed other regions throughout the quarter.

Top Regions (Horizontal Bar Chart) ​

A horizontal bar chart is useful for comparing categories when you have long labels or want to emphasize rankings.

Regional Performance Over Time ​

This grouped bar chart shows how each region's revenue changed month-over-month.

Revenue Composition (Inline Data Example) ​

Sometimes you need a one-off chart with custom data that doesn't need to be reused:

Dashboard 2: Advanced Analytics ​

Advanced chart types including combo charts, dual y-axis, multi-line trends, area charts, and scatter plots.

Actual Revenue vs Target ​

Combo chart showing actual revenue (bars) against target goals (line).

Revenue and Customer Growth (Dual Y-Axis) ​

This chart shows two different scales: revenue (left axis) and customer count (right axis).

Multi-line chart showing weekly revenue trends for each region.

Cumulative Revenue Growth ​

Area chart showing total cumulative revenue across all regions over time.

Regional Revenue Composition Over Time ​

Stacked area chart showing how each region contributes to total revenue week-over-week.

Daily Sales Trend (Responsive Label Test) ​

This chart has many data points (30 days) to demonstrate automatic label reduction on narrow screens. Try resizing the browser to see labels automatically skip.

Regional Market Share Over Time ​

Normalized stacked area chart (100% stacked) showing each region's percentage share of total revenue over time, similar to a time-series pie chart. This chart shows North losing market share to East over the quarter.

Revenue Efficiency Analysis ​

Scatter plot showing the relationship between revenue and profit, sized by unit sales.

Dashboard 3: Product Performance Analysis ​

Advanced data transformations with filtering, calculated measures, and sorting.

Top Products with Complex Filtering ​

This chart demonstrates filtering at both the pre-aggregation (WHERE) and post-aggregation (HAVING) levels.

Profit Margin Analysis ​

Chained calculated measures: profit = revenue - cost, then margin = profit / revenue.

Dashboard 5: Market Share Analysis ​

Pie and doughnut charts for showing proportional data.

Market Share by Category ​

Revenue Distribution by Region ​

Dashboard 6: Advanced Transformations ​

Complex examples with calculated dimensions and chained calculated measures.

Demonstrates calculated dimensions using SQL expressions.

Performance Metrics with Chained Calculations ​

Multiple calculated measures that reference each other.

Phase 1 Customization Features Demo ​

Number Formatting & Data Labels ​

This chart demonstrates three Phase 1 features working together:

  1. Number formatting on axis (.format)
  2. Data labels on marks (.dataLabels)
  3. Axis min/max control

Grid Lines Customization ​

Demonstrating configurable grid lines with custom color and opacity:

Percentage Formatting with Data Labels ​

Perfect for displaying percentages on charts:

SI Prefix Formatting (K, M, B) ​

Using abbreviated number format for large values:

Multi-Line Chart with All Features ​

Combining formatting, grid lines, and data labels on a multi-series chart:

Combo Chart with Formatted Axes ​

Bar + line combo with different formatting on each axis:

Data Labels with Center Positioning ​

Using position: "center" to place labels inside bars:

Interactive Dashboard Parameters ​

This example demonstrates the dashboard parameters pattern for creating interactive dashboards where parameter controls update all charts dynamically.

How It Works ​

1. Define Named Params Block - Creates shared interactive UI controls:

2. Reference Parameters in Charts - Use $blockname.param_id variable syntax:

Complete Dashboard Example ​

Named params block (shared across all charts):

Chart using named params:

Chart with Chart-Level Inline Params:

Parameter Types ​

Available parameter types:

  1. multiselect - Checkbox group for multiple selections

    yaml
    - id: regions
  type: multiselect
  label: "Regions"
  options: ["US", "EU", "APAC"]
  default: ["US"]

  2. select - Dropdown for single selection

    yaml
    - id: category
  type: select
  label: "Category"
  options: ["All", "Electronics", "Clothing"]
  default: "All"

  3. daterange - Start and end date inputs

    yaml
    - id: period
  type: daterange
  label: "Date Range"
  default:
    start: "2024-01-01"
    end: "2024-12-31"

  4. number - Numeric input

    yaml
    - id: threshold
  type: number
  label: "Min Revenue"
  default: 1000

  5. text - Text search input

    yaml
    - id: search
  type: text
  label: "Search Products"
  placeholder: "Enter product name..."
  default: ""

Variable Resolution ​

Nested parameter values are accessed using dot notation (named params):

yaml
aggregate:
  filters:
    rules:
      - field: date
        operator: between
        value: ["$dashboard_filters.date_range.start", "$dashboard_filters.date_range.end"]

Resolution happens before pipeline execution:

  • "$dashboard_filters.region" → ["US", "EU"] (from named params block state)
  • "$dashboard_filters.min_revenue" → 5000 (from named params block state)
  • ChartML pipeline receives resolved values and executes normally

Chart-Level vs Dashboard-Level Parameters ​

Dashboard-Level (standalone params block):

Chart-Level (inline in chart):

Variable Syntax:

  • Dashboard-level params: $blockname.param_id (e.g., $global_filters.global_date_range)
  • Chart-level params: $param_id (e.g., $selected_regions)

Resolution:

  • Has dot → named param from registry (e.g., $global_filters.global_date_range)
  • No dot → chart-level param from inline params: section (e.g., $selected_regions)

Complete Chart-Level Params Example ​

This example shows a chart with its own inline parameters that render above the chart:

How it renders:

  1. Parameter controls appear above the chart (responsive grid layout)
  2. User changes "Regions" multiselect → chart filters to selected regions
  3. User changes "Minimum Revenue" → chart filters to regions above threshold
  4. Parameters only affect this specific chart (not other charts on the page)

When to use chart-level params:

  • ✅ Chart-specific filtering (only applies to one chart)
  • ✅ Self-contained charts that don't share parameters
  • ✅ Rapid prototyping without creating dashboard-level params

When to use dashboard-level params:

  • ✅ Multiple charts share the same parameters
  • ✅ Global filtering across entire dashboard
  • ✅ Cleaner markdown (params defined once at top)

Key Features ​

  • ✅ Parameters defined once - Used across all charts in the dashboard
  • ✅ Chart-level control - Each chart chooses which parameters to use
  • ✅ URL-based sharing - Parameter state stored in URL query params (bookmarkable)
  • ✅ No spec changes - Uses existing transform.filters structure
  • ✅ Portable - Parameter values can come from URL, React state, CLI, config files
  • ✅ Inline rendering - Parameters render where defined in markdown

Implementation Notes ​

How parameter blocks work:

  1. `````chartml``` block with type: params parsed from markdown
  2. Renders interactive DashboardParams component at block location
  3. User changes parameter → updates parameter state → updates URL
  4. Before chart execution: $blockname.param_id variables resolved to actual values
  5. ChartML pipeline executes with resolved parameter values
  6. Charts re-render with filtered data

Benefits:

  • No ChartML spec changes required
  • Parameters are just ChartML blocks with type: params
  • Variable resolution is simple string replacement
  • URL updates enable shareable filtered views
  • Each chart independently chooses which parameters apply

Summary ​

These mock dashboards demonstrate:

Core Features:

  • Reusable sources - Define once, reference multiple times
  • Interactive parameters - Dynamic dashboard filtering with URL-based sharing
  • All chart types - Bar, line, area, scatter, pie, doughnut, table, metric
  • Chart modes - Grouped bars, stacked bars, stacked areas, combo charts, dual y-axis
  • Data transformations - Dimensions, measures, filters, calculations
  • Calculated fields - Pre and post-aggregation calculations
  • Smart filtering - WHERE vs HAVING auto-detection
  • Field references - Chained calculated measures
  • Inline vs source - Both patterns demonstrated
  • Markdown integration - Narrative content with executable specs

Phase 1 Customization Features:

  • Number/Date Formatting - Format axis labels and data labels ($,.0f, .1%, ~s, date formats)
  • Axis Min/Max Control - Override auto-scaling with custom bounds
  • Grid Line Customization - Control visibility, color, opacity, dash patterns (x/y grids)
  • Data Labels on Marks - Display values on bars, lines, and areas with positioning and formatting

Released under the MIT License.

Copyright © 2025 Alytic Pty Ltd