Install
One package for both. It ships compiled JavaScript (ES modules) with type definitions beside it, so a TypeScript project gets types with no extra install and a JavaScript project needs no build step for it.
npm i wobli pnpm add wobli yarn add wobli bun add wobli
Three entry points: wobli is the engine, wobli/react the component, and wobli/icons/<slug> one illustration each, so an app ships only the ones it imports. React is optional.
React
Size the sticker with CSS; the canvas fills its width at 1:1 and renders at device resolution.
// Checkout.tsx
import { Sticker } from 'wobli/react'
import { brand } from 'wobli'
import type { Palette } from 'wobli'
import cardTap from 'wobli/icons/card-tap'
const palette: Palette = brand('#0a84ff', '#ff7a1a')
export function Checkout() {
return (
<>
<Sticker icon={cardTap} style={{ width: 240 }} />
<Sticker icon={cardTap} palette={palette} line={1.5} depth={0.6} />
<Sticker icon={cardTap} loop={false} replayOnHover />
</>
)
}Every sticker on a page shares one animation clock and one requestAnimationFrame loop. Stickers off screen skip their paints, and a still hold costs nothing. Reduced motion shows each illustration's still frame.
Sticker Props
- icon
- Icon
- Any illustration, imported from wobli/icons/<slug>.
- palette
- Partial<Palette>
- Slots to swap over the default. ink is the stroke colour.
- line
- number
- Outline width multiplier. 1 by default, 0 removes every outline.
- depth
- number
- Extrusion multiplier. 1 by default, 0 is flat.
- loop
- boolean
- false plays once when it first shows, then rests on the still frame.
- offset
- number
- Frames ahead of the page clock, to put neighbours out of step.
- enter
- number
- Seconds after it first shows to pop in. Leave out to skip the entrance.
- replayOnHover
- boolean
- Restart the motion when the pointer enters.
- label
- string
- Accessible name. The canvas has role="img".
Loading on Demand
The slug is the last part of an illustration's address on this site. Import it up front, or only when it is about to show.
import { lazy } from 'react'
import { Sticker } from 'wobli/react'
import type { Icon } from 'wobli'
// each illustration is its own module, so it can load when it is needed
async function load(slug: string): Promise<Icon> {
return (await import(`wobli/icons/${slug}.js`)).default
}
// or as a component that suspends until the drawing arrives
const CardTap = lazy(async () => {
const { default: icon } = await import('wobli/icons/card-tap')
return { default: () => <Sticker icon={icon} /> }
})Palette Roles
Each fill names what a part is, so any palette keeps its meaning. 7 named sets ship in PALETTES: riso, candy, matcha, sunset, clay, aqua, system. Or derive one with brand(a, b), mono(hex) or hue(deg), all worked in OKLCH so contrast holds.
mainBodies: the folder, the card, the file tagdeepThe dark second colour: phones, the reader, card stripestintPale fills: screensgoldCoins, stars, the card chipokSuccess: checks, MessageshotAlerts and badgeswhitePaper, banners, buttonsgreySecondary parts: the laptop deck, a folded cornerpaperOff-white panelsinkThe outline: stroke colour
Without React
The engine needs only a canvas, so it works with Vue, Svelte, or no framework at all.
import { play, draw } from 'wobli'
import type { Player, Style } from 'wobli'
import cloudUpload from 'wobli/icons/cloud-upload'
const canvas = document.querySelector<HTMLCanvasElement>('#sticker')!
const player: Player = play(canvas, cloudUpload, { palette: { main: '#5e5ce6' }, line: 1.2 })
player.set({ depth: 0.5 }) // restyle in place, no restart
player.replay()
player.stop()
// one frame, e.g. for an export: scale ctx so 500 units fill the box
const style: Style = { palette: { main: '#5e5ce6' }, line: 1, depth: 1 }
const ctx = canvas.getContext('2d')!
ctx.scale(canvas.width / 500, canvas.width / 500)
draw(ctx, cloudUpload, 124, style)Types
import type { Icon, Palette, PaletteName, Style, PlayOptions, Player } from 'wobli'
// a palette can be partial: only the roles you want to change
const mine: Partial<Palette> = { main: '#5e5ce6', ink: '#1d1d1f' }