Isotype JS

Visualize numbers with meaningful icons – inspired by Otto Neurath’s ISOTYPE system.

---

✨ Features

• Built with TypeScript – includes full typings out-of-the-box
• Fluent builder API (IsotypeChart.create(container))
• SVG/HTML renderer – export as inline SVG or plain DOM icons
• 12+ chart flavours (bar, comparative, timeline, matrix, proportional, population-pyramid, …)
• Built-in responsive & accessibility utilities
• Flexible theming & animation engine (GSAP / CSS)
• Plugin API for custom projections, symbol packs, data transforms

---

📦 Installation

# npm
npm install isotype-js
# yarn
yarn add isotype-js
# pnpm
pnpm add isotype-js

If you prefer a direct <script> tag, grab the UMD build:

<script src="https://unpkg.com/isotype-js/dist/index.umd.js"></script>

The UMD build auto-registers window.Isotype.

---

🏗️ Quick Start (Vanilla JS)

<div id="chart"></div>
<script type="module">
  import { IsotypeChart } from 'isotype-js';

  const data = [
    { label: 'Cats', value: 36 },
    { label: 'Dogs', value: 24 },
    { label: 'Rabbits', value: 12 },
  ];

  // Classic constructor
  new IsotypeChart({
    container: '#chart',
    data,
    type: 'pictorial-unit',
    symbols: {
      primary: '🐾'
    }
  });
</script>

<!-- Or with the fluent builder API -->
<script type="module">
  import { IsotypeChart } from 'isotype-js';
  import { animals } from 'isotype-js/symbols';

  IsotypeChart.create('#chart')
    .data(data)
    .type('pictorial-unit')
    .symbols(animals.paw, { scale: 1 })
    .tooltip('<b>{label}</b><br/>{value} animals')
    .animate('fade-up')
    .render();
</script>

---

📚 API Docs

IsotypeChart(config: IsotypeChartConfig)

Creates a new chart instance. Key config groups:

Key	Purpose
container	CSS selector, HTMLElement or ShadowRoot target
data	DataPoint[] or DataSet[]
type	Chart flavour (`'bar'
symbols	Primary/secondary icons, arrangement, custom library
layout	Fixed / adaptive / fluid sizing & padding
theme	Color & typography tokens
interactions	Hover & click behaviour, tooltips
animation	Durations, easings, stagger values
accessibility	Alt-text, live region announcements

Events (EventManager)

chart.on('hover',  (e) => { /* … */ });
chart.on('click',  (e) => { /* … */ });
chart.on('drillDown', (e) => { /* … */ });

e.type is a union of 'hover' | 'hoverOut' | 'click' | 'drillDown'.

chart.off(type, callback) removes listeners. Calling with only type clears all for that type.

Methods

Method	Description
updateConfig(part)	Merge-update config & re-render
updateData(data)	Replace data & re-render
destroy()	Remove event listeners & DOM nodes

---

🧩 Extending

• Plugins – implement PluginInterface and call chart.use(MyPlugin).
• Custom Symbols – supply raw SVG string (<path> allowed) or element.
• Render Targets – use the low-level SymbolRenderer class to export to canvas/PDF.

---

🗺️ Roadmap

• [ ] Treemap & radial symbol layouts
• [ ] Data‐driven theming (ColorSchemes)
• [ ] Official Vue wrapper

---

📝 License

MIT © 2025 Luca Mack & contributors