icons

icons is a local generator — no url. Point it at a set of uniform icons and it lays them out in a centred grid on a solid backdrop, animates them with a sequence of effect steps, and captures the result as a looping video (mp4) or a single still (png). Use it to show off the icon set a project ships.

{
  name: "icon-set",
  generator: "icons",
  options: {
    dir: "public/icons",   // every image file in the folder, sorted by name
    template: "showcase",
  },
}

You provide uniform, single-colour icons (SVG or PNG). By default each icon is tinted through a CSS mask — its shape comes from the file's alpha and its colour from a fill you control — so single-colour icons can be recoloured live (that's what the recolour interactions animate). Set layout.recolor: false to render the icons natively (original colours); then only the scale / opacity / rotate effects apply.

Interactions are one primitive

Every preset interaction is the same step, differing only in order and stagger:

• A step sweeps one effect (scale, color, opacity, rotate, spin) across the grid.
• order sets each icon's phase across the grid — forward, reverse, rows, columns, diagonal, radial-in/radial-out (a ripple from the centre), spiral, or random. Icons that share a phase (a whole diagonal, a ring) fire together, which is what makes a pattern.
• stagger sets how much of the step's span that phase spreads over: 0 fires every targeted icon at once (a pattern flash), 1 walks them one at a time.

So "scale one at a time", "recolour one at a time", and "recolour many in a pattern" are all this one primitive. Steps fold in order, so you stack them into layered, creative sequences (a colour sweep riding over a scale ripple). The animation is a pure function of time, so the video is frame-stepped (crisp, reproducible) and the still is just that timeline frozen at motion.posterTime.

Config options

Provide at least one icon (via icons and/or dir); everything else has a sensible default. Reference is the interactive view; TypeScript is the same shape in code.

{
  name: "icon-set",
  generator: "icons",
  options: {
    // --- source (icons is local: no url) ---
    dir: "public/icons",              // folder of image files, sorted by name
    // icons: ["public/logo.svg", { src: "assets/star.png" }],  // and/or explicit sources
    // template: "showcase",          // optional preset (your options still win)
    accent: "#7c9cff",

    // --- grid layout & appearance ---
    layout: {
      // columns: 6,                   // optional; auto near-square by default
      gap: 32,
      padding: 64,
      // iconSize: 96,                 // optional; fits the frame by default
      background: "#0b0b0f",
      recolor: true,                  // false = native colours (scale/opacity/rotate only)
    },

    // --- resting state & determinism ---
    base: {
      color: "#f4f4f5",
      scale: 1,
      opacity: 1,
      seed: 1,                        // same seed ⇒ identical "random" sweeps
    },

    // --- the animation (order + stagger = the interaction) ---
    steps: [
      // scale ripple out from the centre, then settle back
      { kind: "scale", at: 0.04, span: 0.4, order: "radial-out", stagger: 0.7, scale: 1.5, hold: 0.15 },
      // recolour to the accent, one icon at a time (forward)
      { kind: "color", at: 0.5, span: 0.42, order: "forward", stagger: 0.85, color: "#7c9cff", hold: 0.2 },
    ],

    // --- the timeline ---
    motion: {
      durationMs: 8000,               // steps' at/span (and posterTime) are fractions of this
      posterTime: 0.5,                // for output.format: "image" — which moment to freeze
    },

    // --- output & encoding ---
    output: {
      format: "video",                // "image" freezes one PNG at motion.posterTime
      width: 1080,
      height: 1080,
      deviceScaleFactor: 2,
      fps: 30,
      crf: 18,
      // fileName: "icon-set.mp4",    // optional; defaults to <slug(name)>.<mp4|png>
    },
  },
}

Icons should be uniform (same canvas size) and, for the recolour effects, single-colour silhouettes — the mask takes the shape from the file's alpha. Turn layout.recolor off to show multi-colour icons in their native colours.

Layout. The grid auto-fits and stays centred in the frame at any width×height: columns defaults to a near-square count for the frame's aspect (set it to drive wide or tall layouts), the icons size up to fill, and a short final row is centred under the full rows — so odd counts (7, 10, 13…) still look balanced, not lopsided. Cells are square, so non-square icons letterbox within their cell. layout.iconSize caps the cell (it's clamped so it can never overflow the frame); leave it off to fill.

Examples

Reach for a template for an instant look, or compose your own steps — the interaction is just an order + stagger on each step. Every clip below is a real icons render of the same 16-icon storefront set.

The showcase template

The default template: "showcase" (used whenever you give no steps): a scale ripple out from the centre, then a forward recolour sweep to the accent — settling back to rest so it loops.

{name: "icon-set",generator: "icons",options: {  dir: "public/icons",  template: "showcase",  accent: "#8a5a3c",  layout: { background: "#1a1714" },  base: { color: "#f6f3ed" },},}

One at a time

stagger: 1 with a forward order walks the effect through the grid one icon at a time — the clearest way to "read out" a whole set.

{name: "icon-rollcall",generator: "icons",options: {  dir: "public/icons",  layout: { background: "#1a1714" },  base: { color: "#f6f3ed" },  steps: [    { kind: "scale", at: 0.05, span: 0.9, order: "forward", stagger: 0.85, scale: 1.6, hold: 0.2 },  ],},}

A pattern, all at once

stagger: 0 fires every targeted icon together; a targets pattern picks the subset — here a checkerboard pulses to one colour, then the alternate rows to another.

{name: "icon-checker",generator: "icons",options: {  dir: "public/icons",  layout: { background: "#1a1714" },  base: { color: "#f6f3ed" },  steps: [    { kind: "color", at: 0.05, span: 0.4, stagger: 0, targets: "checkerboard", color: "#8a5a3c", hold: 0.45 },    { kind: "color", at: 0.52, span: 0.4, stagger: 0, targets: "rows-alt",     color: "#b49a77", hold: 0.45 },  ],},}

Layered motion

Steps fold in order, so stack them — a ripple from the centre, a diagonal colour sweep, and a scattered spin riding on top.

{name: "icon-showpiece",generator: "icons",options: {  dir: "public/icons",  layout: { background: "#1a1714" },  base: { color: "#f6f3ed" },  steps: [    { kind: "scale", at: 0.02, span: 0.5, order: "radial-out", stagger: 0.6, scale: 1.45 },    { kind: "color", at: 0.30, span: 0.5, order: "diagonal",   stagger: 0.6,  color: "#8a5a3c" },    { kind: "spin",  at: 0.55, span: 0.4, order: "random",     stagger: 0.7,  turns: 1 },  ],},}

A still contact sheet

Set output.format: "image" to freeze one moment as a PNG — a clean grid of the whole icon set, with posterTime picking which beat to catch (here the checkerboard mid-flash).

{name: "icon-sheet",generator: "icons",options: {  dir: "public/icons",  template: "pattern",  accent: "#8a5a3c",  layout: { background: "#1a1714" },  base: { color: "#f6f3ed" },  output: { format: "image", width: 900, height: 900 },  motion: { posterTime: 0.25 },},}