Declarative Chart Library

Write (and read!) charts in plain HTML.

Most chart libraries want an empty <div> and a call into an opaque JavaScript library. The data comes either from an extra endpoint or hard-coded into a config object, so a simple chart ends up spread across HTML, JavaScript, and often a server route as well.

This library lets you write charts declaratively in HTML:

<dc-chart width="600" height="400">
  <dc-title>Revenue by Region</dc-title>
  <dc-bar value="4200" label="North"></dc-bar>
  <dc-bar value="3800" label="South"></dc-bar>
  <dc-bar value="5100" label="East"></dc-bar>
</dc-chart>

That image is the output of the markup above, rendered by the library and exported with its own downloadSvg().

Which means your existing template loop already knows how to write it:

<!-- Jinja2 / Flask -->
<dc-chart width="600" height="400">
  <dc-title>Revenue by Region</dc-title>
  {% for region in regions %}
    <dc-bar value="{{ region.revenue }}" label="{{ region.name }}"></dc-bar>
  {% endfor %}
</dc-chart>

<!-- Django - the same loop, with a Django filter doing the rounding -->
<dc-chart width="600" height="400">
  <dc-title>Revenue by Region</dc-title>
  {% for region in regions %}
    <dc-bar value="{{ region.revenue|floatformat:0 }}" label="{{ region.name }}"></dc-bar>
  {% endfor %}
</dc-chart>

<%# Rails %>
<dc-chart width="600" height="400">
  <dc-title>Revenue by Region</dc-title>
  <% @regions.each do |region| %>
    <dc-bar value="<%= region.revenue %>" label="<%= region.name %>"></dc-bar>
  <% end %>
</dc-chart>

No endpoint to build, no serialisation to keep in step with your models, and the chart is in your page's source where you can read (and understand) it.

It updates the way the rest of your page does

A chart watches its own children, so changing the markup is the API. There is no redraw(), no setData(), and no requestUpdate() to remember.

Swap the whole thing — here a server-rendered fragment, fetched and dropped in:

<dc-chart id="sales" width="600" height="400"></dc-chart>

const chart = document.querySelector('#sales');
chart.innerHTML = await (await fetch('/reports/q3')).text();
// Nothing further. The chart notices and redraws.

Or change one part of it. Each of these is the entire update:

// Add a bar
chart.insertAdjacentHTML('beforeend', '<dc-bar value="5100" label="East"></dc-bar>');

// Revise a value
chart.querySelector('dc-bar[label="North"]').setAttribute('value', '4800');

// Hide a series - the legend drops it too
chart.querySelector('dc-line[label="2023"]').hidden = true;

Because it is a MutationObserver over ordinary DOM rather than a framework binding, nothing above is specific to how you got there. The same three lines work from an event handler, from htmx or Turbo swapping the children out, from Alpine, or from a <template> you cloned — the chart never learns which.

Every element passes attributes it does not recognise — data-*, htmx's hx-*, Alpine's x-on:, anything — through to the SVG shape, so a bar can be a drop target or trigger a request. (Inline on* handlers are the one exception; see API.md.)

Where this sits

The useful distinction between charting libraries is not "web component or JS library" — that is cosmetic. It is where the data lives, and on that axis there are only two designs.

Data as a payload. One element, or one call, per chart:

<google-chart data='[["Month","Days"],["Jan",31],["Feb",28]]'></google-chart>

new Chart(ctx, { data: { labels: [...], datasets: [...] } });

Different clothes, same design. The data is an opaque blob you must serialise first, and the HTML is a mounting point. You cannot address one datapoint from markup, attach a handler to a single bar, or let a template emit a row without JSON-encoding it. Chart.js, ECharts, ApexCharts, Highcharts, Recharts, Vega-Lite and the web-component wrappers all work this way.

Data as markup. One element per datapoint:

<td style="--size: 0.4"><span class="data">$40K</span></td>   <!-- Charts.css -->
<dc-bar value="40000" label="Jan"></dc-bar>                    <!-- this library -->

That category has essentially two members. Charts.css proved there is demand for it — 6.5k stars — and stopped where real charting begins, because a stylesheet cannot measure text, compute a nice axis range, lay out a legend, fit labels, or handle interaction. Its markup also asks you to pre-normalise: --size is a ratio from 0 to 1, so the real number never appears in the document except as display text.

This library is the data-as-markup approach with a rendering engine behind it — axes, scales, legends, text fitting, interaction, accessibility — and value="40000" is the actual number, un-normalised, so your template does not need to know the series maximum before it can emit a row.

The engine is the trade. Charts.css needs no JavaScript and this does, so with scripting off a <dc-chart> shows nothing at all. If that matters for your page, supply a fallback table — either in <noscript>, or inside the chart where a dc-chart:defined rule hides it once the library arrives, which also covers a bundle that was blocked or failed to load. Both are plain HTML and neither needs an API: When JavaScript Does Not Run.

More than bars

<dc-chart width="600" height="400">
  <dc-axis position="bottom"><dc-title>Dose (mg)</dc-title></dc-axis>
  <dc-reference min="40" max="60" fill="#16a34a" label="Target range"></dc-reference>
  <dc-scatter label="Control" fill="#2563eb">
    <dc-point x="5" value="12"></dc-point>
    …
  </dc-scatter>
  <dc-scatter label="Treated" fill="#dc2626" shape="triangle">…</dc-scatter>
  <dc-legend position="bottom"></dc-legend>
</dc-chart>

Bar, line, area, bubble, scatter, pie, funnel, stage and radar, with axes, legends, patterns, annotations and keyboard navigation. The examples have all of it.

Where it fits, and where it does not

The sweet spot is small-to-medium categorical data emitted by a server template — a few dozen bars, a handful of series. One element per datapoint has real costs at scale: DOM weight, verbosity, and markup that gets unwieldy past a few hundred points.

Rendering scales close to linearly. On one laptop, a line chart paints 1,000 points in about 170 ms, 5,000 in about 580 ms, and 10,000 in about 1.2 s. A few thousand points is comfortable; very large series are where you start to notice the page working.

Measure it on your own device — that page is the honest answer, since a phone is slower than a laptop and the difference matters more than any figure published here.

A fuller version of this analysis, with the competitive matrix and its caveats, is in docs/review.md.

Features

Declarative Syntax - Define charts with nested HTML elements
Multiple Chart Types - Bar, Line, Area, Bubble, Pie, Funnel, and Stage charts
Rich Styling - Colors, gradients, patterns, and high contrast mode
Number Formatting - Currency, compact (1.2M), percentages, locale-aware
Fully Accessible - ARIA labels, keyboard navigation, screen reader support
Interactive - Popups, clickable elements, dynamic updates
Events - dc-click, dc-mouseenter, dc-mouseleave, dc-render with typed detail
Lightweight - Built on Lit (~5KB overhead)
TypeScript - Full type definitions included
Framework-agnostic - Works with React, Vue, Angular, or plain HTML

Quick Start

Installation

Via npm:

npm install declarative-charts lit

import 'declarative-charts';

Lit is a peer dependency, so you install it alongside. This keeps a single copy of Lit in your app if you already use it — bundling our own would give you two. The CDN builds below need no such thing; they are fully self-contained.

Via CDN:

<script type="module" src="https://unpkg.com/declarative-charts"></script>

Or with jsdelivr:

<script type="module" src="https://cdn.jsdelivr.net/npm/declarative-charts"></script>

Local development:

git clone https://github.com/LarryLustig/declarative-charts.git
cd declarative-charts
npm install
npm run dev

Open your browser to http://localhost:5173

Bar Chart

<dc-chart width="600" height="400">
  <dc-title>Monthly Sales</dc-title>
  <dc-bar value="10" fill="red" label="Jan"></dc-bar>
  <dc-bar value="25" fill="blue" label="Feb"></dc-bar>
  <dc-bar value="15" fill="green" label="Mar"></dc-bar>
</dc-chart>

Line Chart

<dc-chart width="600" height="400">
  <dc-title>Temperature Trends</dc-title>
  <dc-line stroke="#9C27B0" label="City A">
    <dc-point value="15" label="Mon"></dc-point>
    <dc-point value="18" label="Tue"></dc-point>
    <dc-point value="22" label="Wed"></dc-point>
  </dc-line>
</dc-chart>

Area Chart

<dc-chart width="600" height="400">
  <dc-title>Traffic by Source</dc-title>
  <dc-area fill="#2196F3" label="Direct">
    <dc-point value="30" label="Mon"></dc-point>
    <dc-point value="45" label="Tue"></dc-point>
    <dc-point value="38" label="Wed"></dc-point>
  </dc-area>
  <dc-area fill="#4CAF50" label="Referral">
    <dc-point value="20" label="Mon"></dc-point>
    <dc-point value="25" label="Tue"></dc-point>
    <dc-point value="32" label="Wed"></dc-point>
  </dc-area>
</dc-chart>

Areas stack by default; add overlapping to the chart to draw them on top of one another.

Pie Chart

<dc-pie-chart width="600" height="400">
  <dc-title>Market Share</dc-title>
  <dc-pie-slice value="45" label="Product A"></dc-pie-slice>
  <dc-pie-slice value="30" label="Product B"></dc-pie-slice>
  <dc-pie-slice value="25" label="Product C"></dc-pie-slice>
</dc-pie-chart>

Funnel Chart

<dc-funnel-chart width="600" height="400">
  <dc-title>Conversion Funnel</dc-title>
  <dc-funnel-stage value="1000" label="Visitors"></dc-funnel-stage>
  <dc-funnel-stage value="500" label="Leads"></dc-funnel-stage>
  <dc-funnel-stage value="100" label="Customers"></dc-funnel-stage>
</dc-funnel-chart>

Stage Chart

<dc-stage-chart width="400" height="500" stage-size="value">
  <dc-title>Pipeline</dc-title>
  <dc-stage value="100" label="Leads"></dc-stage>
  <dc-stage value="60" label="Qualified"></dc-stage>
  <dc-stage value="20" label="Won"></dc-stage>
</dc-stage-chart>

Like a funnel, a stage chart shows a flow — but it draws each step as a shape whose area is proportional to its value, rather than as a chevron band.

Bubble Chart

<dc-chart width="600" height="400">
  <dc-title>Quarterly Performance</dc-title>
  <dc-bubble label="Q1" value="30" size-value="100"></dc-bubble>
  <dc-bubble label="Q2" value="45" size-value="200"></dc-bubble>
  <dc-bubble label="Q3" value="60" size-value="300"></dc-bubble>
</dc-chart>

Browser Compatibility

Browser	Supported Versions
Chrome	90+
Firefox	90+
Safari	14+
Edge	90+

Requires native support for Web Components (Custom Elements, Shadow DOM) and ES2020. No polyfills needed for modern browsers.

Bundle Size

Three artifacts, because three kinds of consumer need different things. You download exactly one.

Artifact	Lit	Raw	Gzipped	For
`declarative-charts.standalone.js`	inlined	291 KB	75 KB	CDN and vendored `<script type="module">`
`declarative-charts.umd.cjs`	inlined	295 KB	75 KB	plain `<script src>` and `require()`
`declarative-charts.js`	external	456 KB	108 KB	bundlers — yours will minify it

Lit accounts for about 6 KB gzipped of the self-contained builds; the library itself is ~69 KB gzipped. The bundler-facing build is larger because it keeps /* @__PURE__ */ annotations and formatting for your bundler to tree-shake against and minify — it is not what a browser downloads.

Figures from npm run build, which prints them on every build.

Performance Guidelines

Large datasets: For very large datasets, consider aggregating data before rendering.
Dynamic updates: Just change the markup. Charts watch their own children with a MutationObserver, so adding, removing, hiding or re-attributing an element re-renders automatically — requestUpdate() is not needed, and htmx-style innerHTML swaps work as-is.
Hidden elements: Use the hidden attribute on data elements to temporarily hide them without removing from DOM.
Popups: Use auto-popup for automatic tooltips instead of manually managing popup state.
SVG rendering: Charts render to SVG, which scales cleanly but can slow down with thousands of elements.

Documentation

Live examples - 37 pages, every feature, with the markup beside each chart
API Reference - Complete attribute and element documentation
Changelog - Version history
Roadmap - Planned features and explicitly declined ones
Security policy - Threat model and private reporting

Those pages are built from examples/ and published on every push to main. To run them locally, npm run dev and open localhost:5173.

Key Examples

Feature	Example
Bar charts	barcharts.html
Line charts	linecharts.html
Pie charts	piecharts.html
Funnel charts	funnelcharts.html
Colors & gradients	colors.html
Patterns & palettes	palettes.html, patterns.html
Number formatting	formatting.html
Legends & titles	legends.html, titles.html
Axes configuration	axes.html
Popups & interactivity	popups.html, interactive.html
Accessibility	accessibility.html
htmx integration	htmx-integration.html

Development

npm run dev      # Start development server
npm run build    # Build for production
npm test         # Run tests

Project Structure

src/
├── chart.ts            # Bar/Line/Bubble chart component
├── pie-chart.ts        # Pie chart component
├── funnel-chart.ts     # Funnel chart component
├── chart-*.ts          # Data elements (bar, line, point, etc.)
└── index.ts            # Main export

examples/               # Example HTML files

License

MIT - See LICENSE for details.

Name		Name	Last commit message	Last commit date
.github		.github
build		build
docs		docs
examples		examples
public		public
src		src
test		test
.editorconfig		.editorconfig
.gitattributes		.gitattributes
.gitignore		.gitignore
API.md		API.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
ROADMAP.md		ROADMAP.md
SECURITY.md		SECURITY.md
index.html		index.html
package-lock.json		package-lock.json
package.json		package.json
playwright.config.ts		playwright.config.ts
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vite.config.site.ts		vite.config.site.ts
vite.config.standalone.ts		vite.config.standalone.ts
vite.config.ts		vite.config.ts
vitest.config.ts		vitest.config.ts

Navigation Menu

Repository files navigation

Declarative Chart Library

It updates the way the rest of your page does

Where this sits

More than bars

Where it fits, and where it does not

Features

Quick Start

Installation

Bar Chart

Line Chart

Area Chart

Pie Chart

Funnel Chart

Stage Chart

Bubble Chart

Browser Compatibility

Bundle Size

Performance Guidelines

Documentation

Key Examples

Development

Project Structure

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Declarative Chart Library

It updates the way the rest of your page does

Where this sits

More than bars

Where it fits, and where it does not

Features

Quick Start

Installation

Bar Chart

Line Chart

Area Chart

Pie Chart

Funnel Chart

Stage Chart

Bubble Chart

Browser Compatibility

Bundle Size

Performance Guidelines

Documentation

Key Examples

Development

Project Structure

License

About

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages