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' | 'pictorial-unit' | …) | | 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