Evidence Charts

When to use

Invoke when the user asks to:

• Add a chart to an Evidence.dev page ("add a bar chart", "show this data as a line graph", "create a scatter plot")
• Change an existing chart type or configuration
• Understand which chart component to use for a given dataset shape

Evidence.dev Chart Components

Evidence charts are written as Svelte/HTML components inside .md files. Data is provided via SQL query blocks, then referenced by query name in curly braces. All charts are built on ECharts and support synchronized tooltips, annotations, and custom ECharts config overrides.

Quick Reference

LineChart

Display how one or more metrics vary over time.

Minimal usage:

<LineChart data={orders_by_month} x=month y=sales_usd0k />

Common props:

Example — multi-series with secondary axis and bar:

<LineChart
    data={orders_by_month}
    x=month
    y=sales_usd0k
    y2=orders
    y2SeriesType=bar
    yAxisTitle="Sales per Month"
    title="Monthly Performance"
/>

Example — step line with custom palette:

<LineChart
    data={orders_by_category}
    x=month
    y=sales_usd0k
    series=category
    step=true
    colorPalette={['#cf0d06', '#eb5752', '#e88a87', '#fcdad9']}
/>

Annotations (nest inside the chart tag):

<LineChart data={orders_by_month} x=month y=sales yFmt=usd0>
    <ReferenceLine y=9000 label="Target" />
    <ReferenceArea xMin='2020-03-14' xMax='2020-08-15' label="Lockdown" color=warning />
</LineChart>

BarChart

Compare a metric across categories. Supports stacked, grouped, 100% stacked, and horizontal layouts.

Minimal usage:

<BarChart data={orders_by_month} x=month y=sales />

Common props:

Example — horizontal grouped bar:

<BarChart
    data={categories_by_channel}
    x=category
    y=sales
    series=channel
    type=grouped
    swapXY=true
    title="Sales by Channel"
/>

Example — 100% stacked with labels:

<BarChart
    data={orders_by_category}
    x=month
    y=sales
    yFmt=pct0
    series=category
    type=stacked100
    labels=true
/>

Example — dual axis with line overlay:

<BarChart
    data={orders_by_month}
    x=month
    y=sales
    yFmt=usd0k
    y2=num_orders
    y2SeriesType=line
/>

AreaChart

Track how a metric with multiple series changes over time. Emphasizes changes in the sum of series.

Minimal usage:

<AreaChart data={orders_by_month} x=month y=sales />

Common props:

Example — stacked area with formatted axis:

<AreaChart
    data={orders_by_category}
    x=month
    y=sales
    series=category
    yFmt=usd0
/>

Example — 100% stacked with step:

<AreaChart
    data={orders_by_category}
    x=month
    y=sales
    series=category
    type=stacked100
    step=true
/>

ScatterPlot

Show the correlation between two numeric metrics, optionally broken into series.

Minimal usage:

<ScatterPlot data={price_vs_volume} x=price y=number_of_units />

Common props:

Example — multi-series with axis formatting:

<ScatterPlot
    data={price_vs_volume}
    x=price
    y=number_of_units
    xFmt=usd0
    series=category
    tooltipTitle=product_name
/>

Annotations supported via <ReferenceLine> and <ReferenceArea> nested inside.

BubbleChart

Display three metrics per data point: x position, y position, and bubble size.

Minimal usage:

<BubbleChart data={price_vs_volume} x=price y=number_of_units size=total_sales />

Common props:

Example:

<BubbleChart
    data={price_vs_volume}
    x=price
    xFmt=usd0
    y=number_of_units
    series=category
    size=total_sales
    scaleTo=1.5
/>

Histogram

Display the distribution of a metric by automatically binning values into buckets.

Minimal usage:

<Histogram data={orders} x=sales />

Common props:

Example:

<Histogram
    data={orders}
    x=sales
    xAxisTitle="Order Value (USD)"
    fillColor="#476fff"
    title="Order Value Distribution"
/>

FunnelChart

Visualize conversion across sequential stages.

Minimal usage:

<FunnelChart data={funnel_data} nameCol=stage valueCol=customers />

Common props:

Example:

<FunnelChart
    data={funnel_data}
    nameCol=stage
    valueCol=customers
    showPercent=true
    funnelAlign=left
    title="Conversion Funnel"
/>

Heatmap

Show patterns in a single metric across two categorical dimensions using color intensity.

Important: x and y columns must be strings. Cast date columns to string in your SQL before use.

Minimal usage:

<Heatmap data={orders} x=day y=category value=order_count />

Common props:

Example — custom colors with rotated labels:

<Heatmap
    data={item_state}
    x=item
    y=state
    value=orders
    colorScale={['white', 'maroon']}
    xLabelRotation=-45
    cellHeight=25
    title="Item Sales by State"
    rightPadding=40
/>

CalendarHeatmap

Display a daily metric across weeks and months in GitHub contribution graph style.

Minimal usage:

<CalendarHeatmap data={orders_by_day} date=day value=sales />

Common props:

Example — custom color scale, multi-year:

<CalendarHeatmap
    data={orders_by_day}
    date=day
    value=sales
    colorScale={['rgb(254,234,159)', 'rgb(218,66,41)']}
    title="Daily Sales"
/>

BoxPlot

Summarize the distribution of a metric using median, quartiles, and optional whiskers. Requires pre-aggregated data.

Minimal usage (with quartiles):

<BoxPlot
    data={sales_distribution_by_channel}
    name=channel
    intervalBottom=first_quartile
    midpoint=median
    intervalTop=third_quartile
/>

Or use confidence interval shorthand:

<BoxPlot data={experiments} name=experiment midpoint=median confidenceInterval=margin_of_error />

Common props:

Example — horizontal with whiskers:

<BoxPlot
    data={sales_distribution_by_channel}
    name=channel
    min=min
    intervalBottom=first_quartile
    midpoint=median
    intervalTop=third_quartile
    max=max
    yFmt=usd0
    swapXY=true
    title="Daily Sales Distribution"
/>

Sparkline

A compact inline chart for embedding in tables or prose. Renders small and is optimized for space.

Minimal usage:

<Sparkline data={sales_by_date} dateCol=date valueCol=sales />

Common props:

Example — three synced sparklines:

<Sparkline data={sales} dateCol=date valueCol=sales type=bar  valueFmt=usd dateFmt=mmm connectGroup=g1/>
<Sparkline data={sales} dateCol=date valueCol=sales type=area color=maroon valueFmt=usd dateFmt=mmm connectGroup=g1/>
<Sparkline data={sales} dateCol=date valueCol=sales type=line color=purple valueFmt=usd dateFmt=mmm connectGroup=g1/>

SankeyDiagram

Display flows of a metric transferring between categories. Supports multi-level flows via UNION ALL queries.

Minimal usage:

<SankeyDiagram data={traffic_data} sourceCol=source targetCol=target valueCol=count />

Common props:

Example — vertical layout with value labels and gradient links:

<SankeyDiagram
    data={traffic_data}
    sourceCol=source
    targetCol=target
    valueCol=count
    orient=vertical
    nodeLabels=full
    valueFmt=num0k
    linkColor=gradient
    colorPalette={['#ad4940', '#3d8cc4', '#1b5218', '#ebb154']}
    title="Traffic Flow"
/>

Multi-level sankey — union all levels in one query using the same source/target columns:

select channel as source, 'all_traffic' as target, count(*) as count from events group by 1, 2
union all
select 'all_traffic' as source, page_route as target, count(*) as count from events group by 1, 2

Mixed-Type Charts

Combine bar, line, area, scatter, and bubble primitives on a single chart using the <Chart> wrapper.

Basic structure:

<Chart data={fda_recalls}>
    <Bar y=voluntary_recalls />
    <Line y=fda_recalls name="FDA Recalls" />
</Chart>

<Chart> props (same axis/styling props as other charts):

Primitive components and their key props:

Tip: The easiest mixed-type chart is a secondary axis on LineChart or BarChart using y2 and y2SeriesType.

Annotations

All standard charts support nested annotation components: ReferenceLine, ReferenceArea, ReferencePoint, and Callout.

ReferenceLine

Draw a horizontal, vertical, or sloped line.

<!-- Horizontal line at y value -->
<ReferenceLine y=9000 label="Target" />

<!-- Vertical line at x value -->
<ReferenceLine x='2020-03-14' label="Launch" hideValue=true />

<!-- Sloped line between two points -->
<ReferenceLine x='2019-01-01' y=6500 x2='2021-12-01' y2=12000 label="Trend" />

<!-- Lines from a dataset -->
<ReferenceLine data={milestones} x=date label=event_name hideValue />

Key styling props: color, lineColor, lineType (solid/dashed/dotted), lineWidth, labelPosition (aboveStart/aboveCenter/aboveEnd/belowStart/belowCenter/belowEnd), labelColor, bold, italic

Semantic colors: positive, negative, warning, info, base-content-muted

ReferenceArea

Highlight a band or box on the chart.

<!-- X-axis range -->
<ReferenceArea xMin='2020-03-14' xMax='2020-06-30' label="Lockdown" color=warning />

<!-- Y-axis range -->
<ReferenceArea yMin=250 color=positive label="Good" />

<!-- Box (x and y range) -->
<ReferenceArea xMin=16000 xMax=24000 yMin=-0.03 yMax=0.055 label="Target zone" border=true />

<!-- From a dataset -->
<ReferenceArea data={campaigns} xMin=start_date xMax=end_date label=campaign_name />

Key styling props: color, areaColor, opacity, border, borderColor, borderType, labelPosition (topLeft/top/topRight/left/center/right/bottomLeft/bottom/bottomRight), labelColor

ReferencePoint

Annotate a specific x/y coordinate.

<ReferencePoint x="2019-07-01" y=6590 label="Big drop" labelPosition=bottom />

<!-- From a dataset -->
<ReferencePoint data={anomalies} x=date y=value label=description labelPosition=bottom />

Key styling props: color, symbol (circle/rect/triangle/diamond/pin/arrow/none), symbolSize, symbolOpacity, labelPosition (top/right/bottom/left)

Callout

Like ReferencePoint but styled for longer descriptive text.

<Callout x="2021-05-01" y=11012 labelPosition=bottom>
    Sales spike due to
    holiday campaign launch
</Callout>

Custom ECharts

echartsOptions — Override the ECharts config

Available on all standard charts. Note the double curly braces.

<BarChart
    data={query_name}
    x=col_x
    y=col_y
    echartsOptions={{
        legend: {
            right: 'right',
            top: 'middle',
            orient: 'vertical'
        },
        grid: { right: '120px' }
    }}
/>

seriesOptions — Apply options to all series

Avoids repeating per-series config when all series need the same change.

<BarChart
    data={country_sales}
    x=year
    y=sales
    series=country
    seriesOptions={{
        itemStyle: {
            borderWidth: 1,
            borderColor: 'red'
        }
    }}
/>

printEchartsConfig — Debug helper

Add printEchartsConfig=true to any chart to print the full ECharts config below the chart. Useful when writing custom echartsOptions.

<LineChart data={q} x=date y=value printEchartsConfig=true />

ECharts Component — Fully custom charts

Use <ECharts config={...}> for chart types not covered by Evidence components (treemap, pie, donut, gauge, etc.). Data must be included in the config object; spread query results with [...query_name].

<ECharts config={
    {
        tooltip: { formatter: '{b}: {c} ({d}%)' },
        series: [{
            type: 'pie',
            data: [...pie_data]
        }]
    }
}/>

<ECharts config={
    {
        tooltip: { formatter: '{b}: {c} ({d}%)' },
        series: [{
            type: 'pie',
            radius: ['40%', '70%'],  // donut
            data: [...donut_data]
        }]
    }
}/>

For complex configs, define the options object in a <script> tag and reference it:

<script>
let options = {
    title: { text: 'My Chart' },
    series: [{ type: 'treemap', data: [...my_data] }]
};
</script>

<ECharts config={options} />

Full Prop Reference

Props common to most charts

Formatting props

Common format strings: usd, usd0, usd0k, usd1k, pct0, pct1, num0, num0k, mmm (month abbrev), mmm d (month + day)

Axis control props (Line, Bar, Area, Scatter, Bubble, BoxPlot)

Value label props (Line, Bar, Area)

LineChart-specific props

BarChart-specific props

AreaChart-specific props

ScatterPlot-specific props

BubbleChart-specific props

BoxPlot-specific props

Sparkline-specific props

SankeyDiagram-specific props

Heatmap-specific props

CalendarHeatmap-specific props

FunnelChart-specific props

ReferenceLine props

ReferenceArea props

ReferencePoint / Callout props

Parallelisation

Safe — writes only to .md page files. Multiple agents can add different charts to different pages simultaneously.