Configuration

Zero Config Defaults

Uncharted works out of the box with minimal configuration. For most chart types, you only need type and file:

charts:
  sales:
    type: stacked-column
    file: charts/sales.csv

With a CSV like:

quarter,revenue,costs,profit
Q1,100,80,20
Q2,120,90,30
Q3,140,85,55
Q4,160,95,65

Uncharted automatically:

• Uses the first column (quarter) as category labels
• Uses remaining columns (revenue, costs, profit) as data series
• Uses column header names as legend labels
• Calculates appropriate axis scaling from the data

This convention applies to most chart types:

When you need more control—custom labels, axis limits, number formatting—use the axis configuration options described below.

Chart Options

All options available when defining a chart:

Column Definition Formats

Columns can be specified in three ways:

Single column (string):

x:
  column: month

Multiple columns (array - uses column names as labels):

y:
  columns: [prs, commits]

Multiple columns with labels (object):

y:
  columns:
    prs: Pull Requests
    commits: Commits

Axis Properties

Each axis can have these properties:

Axis Keys by Chart Type

Chart Type Examples

Line Chart

charts:
  example:
    type: line
    title: "Trend Over Time"
    file: data.csv

    x:
      column: date
      title: Date
      rotateLabels: true

    y:
      columns:
        visitors: Unique Visitors
        pageviews: Page Views
      max: 100
      title: "Visits"
      format: { compact: true }

    lines: true              # Show connecting lines (default: true)
    dots: true                   # Show dots at data points (default: true)
    # icons: "fa-solid fa-star"  # Optional: use icons instead of dots
    legend: true
    animate: true

Use lines: false to display dots without connecting lines.

Time-Series Chart

charts:
  example:
    type: timeseries
    title: "Population Over Time"
    file: data.csv

    x:
      column: year               # Supports years (1994) or ISO dates (2024-02-17)
      title: Year

    y:
      columns:
        cattle: Cattle
        sheep: Sheep
      title: "Population"
      format: { compact: true }

    dots: false                  # Hide dots (default: false for timeseries)
    # icons: "fa-solid fa-star"  # Optional: icons appear in legend only
    legend: true
    animate: true

Stacked Column Chart

charts:
  example:
    type: stacked-column
    title: "Quarterly Results"
    file: data.csv

    x:
      column: quarter
      rotateLabels: true

    y:
      columns:
        revenue: Revenue
        costs: Costs
        profit: Profit/Loss
      min: -50
      max: 100
      format: { thousands: true }

    legend: true
    animate: true
    downloadData: "Download quarterly data"

Stacked Bar Chart (Horizontal)

charts:
  example:
    type: stacked-bar
    title: "Category Breakdown"
    file: data.csv

    y:
      column: category           # Categories on left side

    x:
      columns:                   # Value series (bars extend right)
        completed: Completed
        pending: Pending
        blocked: Blocked
      max: 100
      format: { compact: true }

    legend: true
    animate: true
    downloadData: true

Bubble Chart

charts:
  example:
    type: bubble
    title: "Quarterly Performance"
    file: data.csv

    x:
      column: quarter            # Categorical X-axis
      title: Quarter

    y:
      column: value
      min: 0
      max: 100
      title: "Performance"
      format: { compact: true }

    series:
      column: metric
      title: Metric              # Legend title

    size:
      column: magnitude
      title: Market Size         # Size legend title

    legend: true
    animate: true

Bubble charts use categorical X-axis (like dot/line) with variable dot sizes (like scatter).

Scatter Chart

charts:
  example:
    type: scatter
    title: "Correlation Analysis"
    file: data.csv

    x:
      column: population
      min: 0
      max: 1000
      title: "Population (millions)"
      format: { compact: true }

    y:
      column: gdp
      min: 0
      max: 50000
      title: "GDP per Capita"
      format:
        thousands: true
        currency: { symbol: "$" }

    label:
      column: country            # Point identifier for tooltips

    series:
      column: region
      title: Region              # Legend title

    size:
      column: area
      title: Land Area           # Size legend title

    # Optional: icons keyed by series value
    icons:
      asia: "fa-solid fa-earth-asia"
      europe: "fa-solid fa-earth-europe"

    proportional: true
    legend: true
    animate: true

Donut/Pie Chart

charts:
  example:
    type: donut
    title: "Market Share"
    file: data.csv

    label:
      column: category           # Segment names (default: first column)

    value:
      column: share              # Segment values (default: second column)
      format:
        compact: true
        currency: { symbol: "$" }

    center:
      value: total
      label: "Total Sales"
    showPercentages: true

    legend: true
    animate: true

Sankey Chart

charts:
  example:
    type: sankey
    title: "Budget Flow"
    file: data.csv

    source:
      column: from

    target:
      column: to

    value:
      column: amount
      format:
        compact: true
        currency: { symbol: "$" }

    nodeWidth: 20
    nodePadding: 10
    endLabelsOutside: true
    proportional: true

    legend: true
    animate: true

Number Formatting

Format options can be specified at the axis level:

Example:

y:
  columns: [revenue, profit]
  format:
    thousands: true
    currency:
      symbol: "$"
      position: before

Plugin Options

Global options passed when registering the plugin:

eleventyConfig.addPlugin(uncharted, {
  dataDir: '_data/charts',       // CSV directory relative to root
  animate: true,                 // enable animations
  cssPath: '/css/uncharted.css', // stylesheet output path
  injectCss: true,               // auto-inject CSS link
  downloadData: true,            // show download links
  downloadImage: true,           // show image download links
  dataPassthrough: true,         // copy CSVs to output
  dataPath: '/data/'             // public path for CSVs
});

Image Generation Options

The image object accepts these properties:

Per-chart image objects can override enabled, width, and height: