# Block libraries

An html block has no network, so it cannot load scripts from a CDN. It names one of these
instead, and Potion injects it: `<!-- potion:use chart.js@4 -->`. Write the `usage` pin of
the entry: it is the version that was tested. Without a directive a block is plain HTML.

| Library | Category | Use it when | Usage |
| --- | --- | --- | --- |
| abcjs (abcjs) | Audio | Showing music as notation — a tune, a scale, an exercise — written as a few lines of ABC text instead of a picture of a score. | `<!-- potion:use abcjs@6 -->` |
| animejs (animejs) | Animation | A few coordinated animations where gsap would be overkill. | `<!-- potion:use animejs@3 -->` |
| apexcharts (apexcharts) | Charts | A chart meant to be explored rather than read once. | `<!-- potion:use apexcharts@4 -->` |
| canvas-confetti (canvas-confetti) | Animation | A celebration beat in something interactive. Rarely the right answer twice. | `<!-- potion:use canvas-confetti@1 -->` |
| caveat (@fontsource/caveat) | Fonts | A block that should read as handwritten notes: a whiteboard explainer, an annotated sketch. System 'cursive' differs on every device; this is the same everywhere. | `<!-- potion:use caveat@5 -->` |
| chart.js (chart.js) | Charts | The default for plotting data. A table beats it for three numbers; reach for it once the shape of the data is the point. | `<!-- potion:use chart.js@4 -->` |
| chroma-js (chroma-js) | Utilities | Building a colour ramp for a heatmap or checking contrast. Note v3 ships no browser build — use v2. | `<!-- potion:use chroma-js@2 -->` |
| compromise (compromise) | Text & search | Pulling structure out of note text — who is mentioned, which topics recur — without an AI call. English only. | `<!-- potion:use compromise@14 -->` |
| d3 (d3) | Charts | A chart no charting library has a name for. Harder to get right than chart.js, so prefer that unless the layout is genuinely custom. | `<!-- potion:use d3@7 -->` |
| dagre (dagre) | Diagrams | A diagram too dense to place by hand: many nodes, crossing links, labelled groups. dagre only computes positions and edge routes; the block draws them as SVG and can make nodes draggable. | `<!-- potion:use dagre@0.8 -->` |
| dayjs (dayjs) | Time | Axis labels, relative times or date maths inside a block. | `<!-- potion:use dayjs@1 -->` |
| diff (diff) | Text & search | Showing what changed between two versions of something inside a note. | `<!-- potion:use diff@9 -->` |
| echarts (echarts) | Charts | Chart types chart.js does not have, or thousands of points. It is 1MB, so do not use it for a bar chart. | `<!-- potion:use echarts@5 -->` |
| event-calendar (@event-calendar/build) | Time | Notes with dates shown as a calendar — due dates, a reading schedule, an agenda built from potion.getNotes(). Suits days and weeks rather than a long history. | `<!-- potion:use event-calendar@5 -->` |
| fabric (fabric) | Drawing | An editor-like surface: place, resize and rotate items. | `<!-- potion:use fabric@6 -->` |
| frappe-charts (frappe-charts) | Charts | A simple chart where echarts or plotly would be wildly oversized. | `<!-- potion:use frappe-charts@1 -->` |
| fuse.js (fuse.js) | Text & search | A search box in a block that should tolerate typos. Exact substring matching does not need this. | `<!-- potion:use fuse.js@7 -->` |
| gridjs (gridjs) | Tables & data | Only when a table needs to be *used* rather than read — sorted, searched, or paged. A plain markdown table is the default and handles most tabular content. | `<!-- potion:use gridjs@6 -->` |
| gsap (gsap) | Animation | Sequenced or choreographed motion. A single transition should stay CSS. | `<!-- potion:use gsap@3 -->` |
| highlight.js (@highlightjs/cdn-assets) | Text & search | Showing code *inside* a block. A plain fenced code block in the note is already highlighted — do not use this for that. Ships a dark theme; restyle .hljs if the block is light. | `<!-- potion:use highlight.js@11 -->` |
| htm (htm) | Interface | Always alongside preact — `const html = htm.bind(preact.h)` gives you JSX syntax a block can actually run. On its own it does nothing. | `<!-- potion:use htm@3 -->` |
| interactjs (interactjs) | Interface | Free positioning or resizing. For simple list reordering, sortablejs is the smaller answer. | `<!-- potion:use interactjs@1 -->` |
| js-yaml (js-yaml) | Tables & data | A block whose data is YAML — config, front matter, a spec pasted into the note. | `<!-- potion:use js-yaml@4 -->` |
| jsmind (jsmind) | Diagrams | Brainstorms and topic maps where hierarchy matters and branches should collapse. A small map that never needs to collapse is simpler as inline SVG. | `<!-- potion:use jsmind@0 -->` |
| jsxgraph (jsxgraph) | Maths | Letting the reader move a slider or drag a point and watch the maths respond — a parameter changing a curve, a tangent following a point, a theorem holding as a triangle moves. | `<!-- potion:use jsxgraph@1 -->` |
| konva (konva) | Drawing | An interactive canvas where the user moves things around. | `<!-- potion:use konva@9 -->` |
| leader-line (leader-line) | Diagrams | Annotating a normal HTML layout with pointers, without moving to a canvas. | `<!-- potion:use leader-line@1 -->` |
| lodash (lodash) | Utilities | Shaping awkward nested data. Modern array methods cover the simple cases without it. | `<!-- potion:use lodash@4 -->` |
| lottie-web (lottie-web) | Animation | A designed animation you already have as Lottie JSON, inlined into the block. | `<!-- potion:use lottie-web@5 -->` |
| luxon (luxon) | Time | Anything involving zones, durations or calendar maths. For plain formatting, dayjs is smaller. | `<!-- potion:use luxon@3 -->` |
| maplibre-gl (maplibre-gl) | Maps | Showing where things are: notes that carry coordinates as properties, stops on a trip, one place. Not for a simple list of addresses, which markdown shows fine. | `<!-- potion:use maplibre-gl@4 -->` |
| mark.js (mark.js) | Text & search | A block that shows text and lets the reader search it, so matches light up in place. | `<!-- potion:use mark.js@8 -->` |
| marked (marked) | Text & search | Rendering markdown the block itself holds as data. The note's own body is already markdown — do not use it for that. | `<!-- potion:use marked@18 -->` |
| mathjs (mathjs) | Maths | A calculator, unit converter or formula sheet — anything where the user types an expression rather than numbers into fixed fields. | `<!-- potion:use mathjs@15 -->` |
| matter-js (matter-js) | Drawing | Something that should fall, bounce or swing. Explaining a physical idea beats decorating with it. | `<!-- potion:use matter-js@0 -->` |
| minisearch (minisearch) | Text & search | A search box over note titles or contents inside a dashboard. fuse.js is better for fuzzy matching a short list; this is for ranked search over longer text. | `<!-- potion:use minisearch@7 -->` |
| nouislider (nouislider) | Interface | Letting the reader vary an input and watch the block respond — the difference between a figure and a model. | `<!-- potion:use nouislider@15 -->` |
| p5 (p5) | Drawing | Something procedural or hand-animated. Static diagrams and simple shapes belong in inline SVG. | `<!-- potion:use p5@1 -->` |
| papaparse (papaparse) | Tables & data | Turning pasted CSV into rows for a table or chart. Hand-rolled split(',') breaks on quoted fields. | `<!-- potion:use papaparse@5 -->` |
| paper (paper) | Drawing | Real geometry work — intersections, offsets, path manipulation. | `<!-- potion:use paper@0.12 -->` |
| pixi.js (pixi.js) | Drawing | Far more moving objects than canvas 2D can keep smooth. It is 800KB, so not for a handful of shapes. | `<!-- potion:use pixi.js@4 -->` |
| plotly.js-basic-dist (plotly.js-basic-dist) | Charts | Analysis output rather than a dashboard tile: error bars, log axes, many scatter points. The basic bundle has only scatter, bar and pie traces — no box plots, histograms or heatmaps (use echarts for those). | `<!-- potion:use plotly.js-basic-dist@2 -->` |
| preact (preact) | Interface | A block whose UI has real state — a filter, a toggle, a list that re-renders. Plain DOM is the default; reach for this when hand-written innerHTML starts fighting you. Pair with htm for JSX-like markup, since a block has no build step. | `<!-- potion:use preact@10 -->` |
| qrcode-generator (qrcode-generator) | Utilities | Putting a link on screen for someone to scan off the page. | `<!-- potion:use qrcode-generator@1 -->` |
| rough-notation (rough-notation) | Drawing | Marking up words that are already on the page — circle a term, underline a claim, bracket a paragraph. It follows the element, so the mark stays on its words when the text reflows; hand-placed roughjs shapes do not. | `<!-- potion:use rough-notation@0 -->` |
| roughjs (roughjs) | Drawing | A diagram that should read as a sketch rather than a finished figure. | `<!-- potion:use roughjs@4 -->` |
| simple-statistics (simple-statistics) | Tables & data | A trend line, an r value, quartiles — numbers you would otherwise get subtly wrong. | `<!-- potion:use simple-statistics@7 -->` |
| sketch (@ghostmind-dev/sketch) | Drawing | Explaining an idea the way a maths video does — an equation built up with circled terms, arrows and notes, over several boards when the idea has steps. One JSON scene; no drawing code, no network, no web fonts. | `<!-- potion:use sketch@0.6 -->` |
| smiles-drawer (smiles-drawer) | Diagrams | Drawing a molecule — caffeine, aspirin, a reaction product — from its SMILES string, which markup cannot lay out. | `<!-- potion:use smiles-drawer@2 -->` |
| sortablejs (sortablejs) | Interface | A block where the reader arranges things — ranking, planning, sorting into columns. | `<!-- potion:use sortablejs@1 -->` |
| swiper (swiper) | Interface | A slide deck or a swipeable gallery inside a note — and it works with a thumb on iOS. | `<!-- potion:use swiper@14 -->` |
| tabulator (tabulator-tables) | Tables & data | Exploring many notes as rows — group films by style, sort by rating, filter as you type. gridjs is lighter for a plain sortable table. Edits made in the table stay in the block; a block cannot write back. | `<!-- potion:use tabulator@6 -->` |
| temml (temml) | Maths | An equation inside a block — a note's own $…$ maths does not reach into html blocks. MathML needs no fonts, so it works in the sandbox where KaTeX would not. | `<!-- potion:use temml@0.13 -->` |
| three (three) | 3D | Something that has to be seen in three dimensions and turned: a molecule, a room, a solar system, a product, a 3D chart. For flat drawing or 2D animation use a canvas or SVG; this is the heaviest library on the list. | `<!-- potion:use three@<version> -->` |
| tonal (tonal) | Audio | Explaining how music is built — the notes of a scale, the chords in a key, the interval between two notes — computed rather than typed out by hand. Pairs with abcjs to show it and tone to hear it. | `<!-- potion:use tonal@6 -->` |
| tone (tone) | Audio | Making sound in a note — a scale, a rhythm, an audible demonstration. Never start audio without the reader asking for it. | `<!-- potion:use tone@15 -->` |
| two.js (two.js) | Drawing | Clean vector shapes and smooth motion without p5's sketch framing. | `<!-- potion:use two.js@0.8 -->` |
| wordcloud (wordcloud) | Text & search | Showing which words or tags dominate a set of notes at a glance. A bar chart is better when exact counts matter. | `<!-- potion:use wordcloud@1 -->` |
| zdog (zdog) | Drawing | A small 3D-looking object the reader can spin — an icon, a model, a playful illustration — without a full 3D engine. | `<!-- potion:use zdog@1 -->` |

The catalog as JSON, with sandbox notes per library: https://potion.run/api/vendor