Charts with ECharts¶

Exercise charts-echarts-annex.pdf · PDF

Look at a report table with 36 rows and try to answer: which folder has the most words? You will need between five and ten seconds, hunting through the group footers. Now look at a bar chart of the same data. Same question: under a second.

The numbers did not change. The shape did the reading for you, because your eyes compare lengths before you can read a digit. A table is for looking up a number. A chart is for seeing a pattern. A report needs both, and today yours gets its chart.

A Scot with no data¶

In 1786, in London, the Scottish engineer William Playfair published The Commercial and Political Atlas. It held 43 charts of England's trade over time, drawn as lines. Money drawn as a line was a new idea.

One more chart was different. For Scotland he only had the figures of a single year, with 17 trading partners. No time, so no line. He drew bars instead. One of the most common charts in the world was born because some data was missing. In 1801, in The Statistical Breviary, he added what is probably the first pie chart.

Why did he not draw Scotland as a line? Because a line needs time along the horizontal axis, and he had categories. He did not choose the chart he liked. The data and the question chose it, and that is still the rule today.

Four tools, four questions¶

We will keep one picture all the way through this page: a toolbox. A hammer is not better than a screwdriver. It is for a different job. Each chart type is a tool for one kind of question.

Three rules go with the toolbox:

• Bars start at zero. The eye compares lengths. Cut the bottom, and the lengths lie.
• A pie has five slices at most, and they are parts of one whole that adds up to 100%. Twelve slices are twelve bars.
• No question, no chart. If you cannot write the question, the chart is decoration.

ECharts in three steps¶

Apache ECharts is a free, open-source JavaScript library for drawing charts.

It was born at Baidu in 2013, entered the Apache Software Foundation's incubator in January 2018, and was announced as a top-level Apache project in January 2021. The code on this page was checked on version 6.1. Older tutorials may look different, because version 6 changed the default theme, but the options work the same way.

Using it takes three steps:

const chart = echarts.init(div);   // 1 · a <div> with a height becomes a chart
chart.setOption(option);           // 2 · the option says WHAT to draw
chart.dispose();                   // 3 · when the div goes away, free the chart

Where are the loops and the rectangles? Nowhere. ECharts is declarative: you describe the chart in an object called the option, and the library draws it. You already work like that: a Svelte component describes the page, and it does not draw pixels.

You can see every chart type, with its option, at echarts.apache.org/examples.

Chart.svelte: build the workbench once¶

ECharts knows nothing about Svelte. It wants a real <div>. So you wrap it in a component, once, and never touch echarts.init again.

npm install echarts

New file src/lib/Chart.svelte:

<script>
  import * as echarts from 'echarts';

  let { option, label, height = 320 } = $props();

  let el;
  let chart;

  // Create the chart once the <div> exists; destroy it when the component goes away.
  $effect(() => {
    chart = echarts.init(el);
    const observer = new ResizeObserver(() => chart.resize());
    observer.observe(el);
    return () => {
      observer.disconnect();
      chart.dispose();
    };
  });

  // Runs again every time `option` changes: new data in, same chart.
  $effect(() => {
    chart.setOption(option, { notMerge: true });
  });
</script>

<div bind:this={el} role="img" aria-label={label} style:height="{height}px"></div>

Four questions you should be able to answer about this file:

{ notMerge: true } makes the new option replace the old one, instead of merging into it.

The bar chart, from the groups¶

The groups you built in the previous lesson are already the data of the chart. In +page.svelte, add to the script:

import Chart from '#lib/Chart.svelte';

// Chart 1 · comparison between categories → bar
let wordsOption = $derived({
  title: { text: 'Words per folder' },
  color: ['#1f5fd1'],
  tooltip: {},
  dataset: { source: groups.map((g) => ({ folder: g.folder, words: g.words })) },
  xAxis: { type: 'category' },
  yAxis: { type: 'value', name: 'words' },
  series: [{ type: 'bar', encode: { x: 'folder', y: 'words' }, label: { show: true, position: 'top' } }]
});

And in the markup, above the table and inside the {:else} (no rows, no chart):

<Chart option={wordsOption}
  label="Bar chart: total words per folder. The table below has the same numbers." />

Now change the folder filter to School: one bar, 5217. Which line of your code redrew the chart? None of them did it directly:

flowchart LR
    F["<b>Filters</b><br>$state"] --> R["<b>rows, groups</b><br>$derived"]
    R --> O["<b>wordsOption</b><br>$derived"]
    O --> E["<b>Second effect</b><br>of Chart.svelte"]
    E --> C["<b>setOption</b><br>the chart redraws"]

The second effect is the bridge. ECharts does not read your $state by itself: the effect hands it each new option.

Read the option back and match each key with what it produced:

The line chart, on your own¶

Your second chart: notes created per month, a line. You need a new grouping and a new option. Here is what the function must return:

// report.js
export function countByMonth(rows) { /* ... */ }
// → [{ month: '2026-09', notes: 9 }, { month: '2026-10', notes: 8 }, { month: '2026-11', notes: 9 },
//    { month: '2026-12', notes: 7 }, { month: '2027-01', notes: 3 }]

Three hints, in order. groupByFolder groups by n.folder: what do you group by now? The month is the first seven characters of created. And to sort by month, remember that ISO text sorts like the calendar.

export function countByMonth(rows) {
  const groups = Object.groupBy(rows, (n) => n.created.slice(0, 7));
  return Object.entries(groups)
    .map(([month, notes]) => ({ month, notes: notes.length }))
    .sort((a, b) => a.month.localeCompare(b.month));
}

// Chart 2 · change over time → line
let monthsOption = $derived({
  title: { text: 'Notes created per month' },
  color: ['#d92b1c'],
  tooltip: { trigger: 'axis' },
  dataset: { source: countByMonth(rows) },
  xAxis: { type: 'category' },
  yAxis: { type: 'value', name: 'notes', minInterval: 1 },
  series: [{ type: 'line', encode: { x: 'month', y: 'notes' }, label: { show: true } }]
});

Put both charts in one row with a CSS grid. In a narrow window they stack by themselves:

.charts { display: grid; grid-template-columns: repeat(auto-fit, minmax(320px, 1fr)); gap: 16px; }

let pinnedOption = $derived({
  title: { text: 'Pinned notes' },
  tooltip: {},
  dataset: {
    source: [
      { name: 'Pinned', value: rows.filter((n) => n.pinned).length },
      { name: 'Not pinned', value: rows.filter((n) => !n.pinned).length }
    ]
  },
  series: [{ type: 'pie', radius: ['40%', '70%'], encode: { itemName: 'name', value: 'value' } }]
});

An honest chart¶

Add one small thing to the bar chart:

yAxis: { type: 'value', name: 'words', min: 1500 },

School now towers six times over Work, and Shopping has vanished. How many times more words does School really have than Work? 5217 ÷ 2070 = 2.5. It is the same data and the same library, telling a different story. Now take min out again. News charts do this all the time, and now you know where to look first: the bottom of the value axis.

Here is a subtler lie. Your line chart says 9, 8, 9, 7 and then 3. Did the user stop writing in January? No: the data ends on 12 January. Half a month looks like a fall. An honest report says so in its header ("data until 12/01/2027"), or leaves the unfinished period out.

Tick this list for every chart you make:

• The title says what is measured
• The value axis has a name
• Bars start from zero
• The values are labelled
• It has an accessible name
• The table with the same numbers is on the page

A chart for your report¶

Open your wireframe. Before any code, write one sentence:

My chart answers the question "...", so the tool is a ...

A missing question means no chart yet. Then copy Chart.svelte into your project, write the grouping in your report.js and the option in your page. Your chart must react to your filter and pass the honest chart list.

Key takeaways¶

• The question chooses the chart: compare → bar, time → line, parts of a whole → pie, relation → scatter, look up → table.
• William Playfair drew the line and the bar in 1786, and he chose by the data he had.
• ECharts is declarative: init once, then many setOption, and dispose at the end.
• Chart.svelte needs two effects: one creates the chart, and the other hands it each new option. Because the option is $derived, the chart reacts to the filters.
• Bars start at zero, and an unfinished period must say so.
• A chart needs an accessible name, and the table stays on the page.

Quick check¶

The same report can now be read at a glance on a screen. Next it goes on paper, in a PDF nobody draws by hand: PDF reports with Typst.