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
Chart error: YAML parse error: data did not match any variant of untagged enum ChartMLSpec

Set Dashboard-Level Default Style ​

All charts below will inherit corporate_theme automatically:

yaml
type: config
version: 1
style: corporate_theme
Chart error: Invalid spec: No chart or params component found

Charts Automatically Inherit the Theme ​

Chart 1: Revenue Trend - Uses all defaults from corporate_theme

JanFebMar050,000100,000150,000200,000

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

JanFebMar0100200300400500600

Chart with Selective Overrides (Deep Merge) ​

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

USEU

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:

Total Revenue$1,234,567↑ 12.2%
Active Users8,432↑ 4.1%
Conversion Rate4.2%↑ 10.5%
Avg Order Value$156.78↑ 10.0%

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:

revenue$45,000
Total Revenue$45,000
Revenue$45,000

Error Rate Example (inverted trend):

Error Rate2.30%↓ 25.8%

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:

JanFebMarAprMayJun$0K$50K$100K$150K$200KRevenue ($)Monthly Goal

Revenue Trend with Target Range ​

Shows revenue trend with a target range band:

JanFebMarAprMayJun$0K$50K$100K$150K$200KRevenue ($)Target Range

Combo Chart: Actual vs Target with Stretch Goal ​

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

JanFebMarAprMayJun$0K$50K$100K$150K$200KRevenue ($)Healthy RangeStretch GoalActual RevenueTarget

Event Marker: Product Launch Impact ​

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

Mar 10Mar 11Mar 12Mar 13Mar 14Mar 15Mar 16Mar 17Mar 180K2K4K6K8KDaily SalesProduct Launch

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:

Chart error: Invalid spec: No chart or params component found

Monthly Revenue Trend ​

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

Chart error: Data error: Named data source 'q1_sales' not found

Revenue Distribution by Region ​

The North region consistently outperformed other regions throughout the quarter.

Chart error: Data error: Named data source 'q1_sales' not found

Top Regions (Horizontal Bar Chart) ​

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

Chart error: Data error: Named data source 'q1_sales' not found

Regional Performance Over Time ​

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

Chart error: Data error: Named data source 'q1_sales' not found

Revenue Composition (Inline Data Example) ​

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

JanFebMar050,000100,000150,000200,000HardwareSoftwareServices

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).

JanFebMar050,000100,000150,000200,000Actual RevenueTarget

Revenue and Customer Growth (Dual Y-Axis) ​

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

JanFebMar$0K$50K$100K$150K$200KRevenue ($)0100200300400500600Customersrevenuecustomers

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

Week 1Week 2Week 3Week 4010,00020,00030,00040,00050,00060,000NorthSouthEast

Cumulative Revenue Growth ​

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

Week 1Week 2Week 3Week 4Week 5Week 6050,000100,000150,000200,000Revenue ($)

Regional Revenue Composition Over Time ​

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

Week 1Week 2Week 3Week 4Week 5Week 6050,000100,000150,000200,000Revenue ($)NorthSouthEast

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.

Day 1Day 3Day 5Day 7Day 9Day 11Day 13Day 15Day 17Day 19Day 21Day 23Day 25Day 27Day 2905,00010,00015,00020,00025,000Sales ($)

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.

Week 1Week 2Week 3Week 4Week 5Week 60%20%40%60%80%100%Market ShareNorthSouthEast

Revenue Efficiency Analysis ​

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

20K30K40K50K60K70K80K90K100K60K70K80K90K100K110K120K130K140K150K160KHardwareSoftwareServices

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.

Gadget XWidget AWidget B01,0002,0003,0004,0005,000

Profit Margin Analysis ​

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

HardwareSoftwareServices0.00.10.20.30.40.50.60.7

Dashboard 5: Market Share Analysis ​

Pie and doughnut charts for showing proportional data.

Market Share by Category ​

ElectronicsHardwareSoftwareServices

Revenue Distribution by Region ​

North AmericaEuropeAsia PacificLatin America

Dashboard 6: Advanced Transformations ​

Complex examples with calculated dimensions and chained calculated measures.

Demonstrates calculated dimensions using SQL expressions.

01,0002,0003,0004,0005,0006,000Widget AWidget B

Performance Metrics with Chained Calculations ​

Multiple calculated measures that reference each other.

EastNorthSouth020,00040,00060,00080,000100,000

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
JanFebMarAprMayJun$0K$10K$20K$30K$40K$50K$60K$70KRevenue ($)$45,000$52,000$48,000$61,000$58,000$67,000

Grid Lines Customization ​

Demonstrating configurable grid lines with custom color and opacity:

JanFebMarAprMayJun$0K$10K$20K$30K$40K$50K$60KSales

Percentage Formatting with Data Labels ​

Perfect for displaying percentages on charts:

EmailSocialSearchDirectReferral0.0%2.0%4.0%6.0%8.0%Conversion Rate4.2%2.8%5.5%6.7%3.1%

SI Prefix Formatting (K, M, B) ​

Using abbreviated number format for large values:

EnterpriseProfessionalStarterPremium0M1M2M3M4MRevenue4.5M2.8M950k1.75M

Multi-Line Chart with All Features ​

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

JanFebMarAprMayJun$0K$20K$40K$60K$80K$100K$120KAmount ($)Actual RevenueTarget$85,000$92,000$88,000$105,000$98,000$112,000$90,000$90,000$95,000$95,000$100,000$100,000

Combo Chart with Formatted Axes ​

Bar + line combo with different formatting on each axis:

Q1Q2Q3Q4$0K$50K$100K$150K$200K$250K$300KRevenue ($)02004006008001,0001,2001,400Customers$285,000$312,000$298,000$345,0001,2501,3801,3201,520RevenueCustomers

Data Labels with Center Positioning ​

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

ElectronicsApparelHomeSports$0K$20K$40K$60K$80K$100K$120K$140KRevenue ($)$125,000$98,000$82,000$67,000

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:

Region
US, EU
Date Range
2024-01-01 → 2024-12-31
Minimum Revenue ($)
1000

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

Chart error: Data error: No category values found

Complete Dashboard Example ​

Named params block (shared across all charts):

Region
US, EU
Minimum Revenue ($)
5000

Chart using named params:

Chart error: Data error: No category values found

Chart with Chart-Level Inline Params:

Widget AWidget BWidget C010,00020,00030,00040,00050,000

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
transform:
  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):

Date Range
2024-01-01 → 2024-12-31

Chart-Level (inline in chart):

USEUAPAC05,00010,00015,00020,00025,000

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:

USEU$0K$10K$20K$30K$40K$50K$60KRevenue ($)

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