@withicons/dynamic

@withicons/dynamic

Live icons for with icons: icons whose content you set. A calendar shows the date you pass, a clock shows your time, a badge shows a count, a battery shows its charge, a weather icon shows the temperature, a tag shows a short label.

Each live icon is a small generator. You give it params, it draws the icon, and any of the 34 styles renders it: line, solid, duo, gloss, engrave, blueprint, sketch, glass, kawaii, sticker, pixel, retro, luxe, bauhaus, skeuo, anime, gothic, pastel, coquette, plush, clay, bento, suite, dock, liquid, chrome, soft3d, brutal, utsav, rangoli, halloween, christmas, lunar, valentine. Text uses the with icons stroke font, so it takes on each style's look, needs no font files and stays readable down to 16px. When a value can't be drawn legibly, the icon switches to something that can: "99+" for big counts, or a level bar in place of a percentage that doesn't fit.

50 live icons, version 0.6.0. Browse and edit them at https://withicons.com.

npm i @withicons/dynamic

Plain HTML (no build step)

<script src="https://cdn.jsdelivr.net/npm/@withicons/dynamic@latest/dist/cdn/lite.js"></script>

<with-live-icon name="calendar-date" day="17" month="MAR"></with-live-icon>
<with-live-icon name="calendar-date" today variant="glass" size="48" label="Today"></with-live-icon>

The script defines <with-live-icon> and window.WithLive, and downloads only what the page draws: the line style is built in, each live icon's drawing code is its own small file (gens/<name>.js next to lite.js), and the first time you use another style, its file (styles/<style>.js) loads. Every name, param and example is known at once (WithLive.list(), get(), validate()); WithLive.render() is sync once the icon and style are loaded (await WithLive.loadIcon(name) and await WithLive.load(style)), and renderAsync() loads both by itself.

cdn/dynamic.js is the same script with all 50 live icons inline, for pages that call WithLive.render() on any icon synchronously. See Bundle size.

The element

<script type="module">import '@withicons/dynamic/element'</script>

<with-live-icon name="battery-level" level="0.42" variant="skeuo" size="64"></with-live-icon>

Change any attribute or JS property (el.variant = 'luxe', el.params = { day: 3 }) and the icon redraws. After each draw the element fires a with-live-render event.

When the same param comes from more than one place (its own attribute, the JSON params, today), the one set last wins. In markup that is the attribute written later; from script, el.params = { day: 3 } overrides an earlier day="17", and setting day again afterwards overrides params.

Styles that take longer than a frame to draw (see Performance) never block the page: the element keeps its current drawing, renders the new one in the background, and shows only the newest params when several changes arrive at once.

Change values live

The element redraws whenever an attribute changes, so values from an API, a WebSocket, a timer or a click are one setAttribute away. Add animate and every change moves to its new value instead of jumping:

<with-live-icon id="unread" name="bell-count" count="3" animate></with-live-icon>
<script>
  const icon = document.getElementById('unread')
  const socket = new WebSocket('wss://example.com/live/bell')
  socket.onmessage = e => icon.setAttribute('count', JSON.parse(e.data).count)   // 3 rolls up to 7
</script>

el.animateTo({ count: 7 }, { ms: 900 }) (or animateTo(el, values, options) from @withicons/dynamic/element, and WithLive.animateTo in the CDN script) animates one change without the attribute and resolves once the new values are drawn. Several attributes set in the same task become one transition, and a new value mid-way retargets from what is on screen.

The last frame is always exactly the new value. Cheap styles (line, duo, blueprint, sketch, pixel) move every frame; slower styles draw a few frames ahead in the render worker and play them from the cache, so a transition never blocks the page. With prefers-reduced-motion: reduce (or setMotion({ reduced: true })) values change at once. In React and Vue, pass animate (or a duration in ms) to <LiveIcon> and change the props.

For your own painting, transition(name, from, to, style, { ms, paint(params), done }) runs the same planner and interpolate(name, from, to, t) returns the params at any point.

JavaScript

import { render, list, get, defaults, validate } from '@withicons/dynamic'

render('calendar-date', { day: 9, month: 'MAY' })                      // '<svg ...>' in line
render('calendar-date', { day: 9, month: 'MAY' }, 'glass', { size: 48, label: '9 May' })
render('bell-count', { count: 120 }, 'sticker')                        // shows 99+
list()                     // every live icon name
get('calendar-date')       // { title, category, params, examples, defaults, aliases, ... }
validate('calendar-date', { day: 40 })   // ['day=40: outside 1..31']

• render(name, params, style = 'line', options) returns an SVG string. It runs synchronously and caches results. Params are lenient: missing ones use the defaults, numbers are clamped, and text is upper-cased and cut to length. Options: size, color, vars, label, class, strokeWidth, absoluteStrokeWidth, and flat. flat resolves CSS variables to plain colours for <img>, canvas and email.
• dataUri(...) takes the same arguments and returns a data: URI.
• renderAsync(...) loads the style first if it isn't loaded yet, and draws rich styles off the main thread. Pass { latest: true } for sliders and live previews: only the newest pending call per icon and style is drawn, and the replaced ones reject with code WITH_SUPERSEDED.
• warm(name, params, style) draws in the background so a later render() is instant; cached(...) tells you if it already is.
• loaded(style) says whether the style's renderer runs on this thread. In the lite and CDN builds a rich style can be drawn only by the render workers, so loaded(style) can stay false while renderAsync() and <with-live-icon> draw it fine; check cached(...) (or await renderAsync()) rather than loaded() before a sync render().
• Metadata: list(), catalog(), get(name), defaults(name), paramsOf(name).
• Params: resolve(name, params) fills in and corrects values; validate(name, params) checks them strictly.
• now() returns today's params { day, month, weekday, year, time }, for example render('calendar-date', now()).
• describe(name, params) says what the icon shows: 'Calendar date, March 17' (the default accessible name).
• Motion: transition(), plan(), interpolate(), setMotion(), reducedMotion() (see Change values live).
• skeleton(name, params) returns the raw drawing, and nodes(name, params, style) returns the [tag, attrs] list.

Bundle size

@withicons/dynamic has every style built in, so render() always works synchronously, in Node and in the browser. Use @withicons/dynamic/lite to keep a page small: it has only the line style, and other styles load the first time you use them.

import { load, render, renderAsync } from '@withicons/dynamic/lite'
await load('kawaii')                                  // or: import '@withicons/dynamic/styles/kawaii'
render('weather', { condition: 'rain', temperature: 12 }, 'kawaii')
await renderAsync('battery-level', { level: 0.2 }, 'luxe')

Performance

Every result is cached, so a repeat render is free. A new render costs what its style costs: stroke styles draw in a few milliseconds, while the rich styles build whole-icon geometry (fields, bevels, boolean layers).

Medians over the 50 live icons on a laptop; the largest icons (alarm clock, gauges) take two to three times as long.

cost(style) returns the current estimate, a moving average of what this device measured. In the browser, <with-live-icon> and renderAsync() send any style slower than a frame to a render worker (dist/worker.js for the ES module builds, the CDN script itself for the classic build). The result is byte-identical to a main-thread render. If a worker cannot start (a file:// page, a CSP without worker-src blob:, or Node), renders run on the main thread one per task, so the page still paints and takes input between icons. Synchronous render() always runs where you call it: for many rich icons, prefer the element, renderAsync() or warm(), or render on the server.

The worker starts on the first render of a rich style, never at load: a page that only shows cheap styles (line, duo, blueprint...) never downloads it. Inside the worker each style is a separate chunk loaded on demand.

Vite: bundle workers as ES modules, so those style chunks stay separate files (with Vite's default iife worker format every style is inlined into one large worker file, and the build is much slower):

// vite.config.js
export default { worker: { format: 'es' } }

webpack 5 keeps the worker's chunks split by default.

React

import { LiveIcon } from '@withicons/dynamic/react'

<LiveIcon name="calendar-date" day={17} month="MAR" variant="glass" size={48} />
<LiveIcon name="calendar-date" today label="Today" />
<LiveIcon name="bell-count" count={unread} className="nav-icon" onClick={open} />
<LiveIcon name="battery-level" level={charge} animate />          // moves to each new level

The icon's params are props. A param with the same name as a wrapper prop (for example label on keycap) goes in params={{ label: 'A' }}. Other props (className, style, onClick, aria-*, data-*) go on the <svg>. Styles other than line load on first use, and an empty svg of the same size holds the space until then. With server rendering, import the styles you use (import '@withicons/dynamic/styles/glass') so the first render is complete.

Vue

<script setup>
import { LiveIcon } from '@withicons/dynamic/vue'
</script>

<template>
  <LiveIcon name="calendar-date" :day="17" month="MAR" variant="glass" :size="48" />
  <LiveIcon name="clock-time" time="10:10" variant="bauhaus" />
  <LiveIcon name="bell-count" :count="unread" animate />
</template>

Live icons and their params

Each table row gives a param's name, type, range or options, default, and what it does.

charts

commerce

communication

devices

files

layout

maps

media

objects

status

time

users

weather

Params, in plain words

License

MIT. Part of with icons, powered by Evergrow.