shad-fx

Install

Take the whole library, or a renderer and the effects you want:

npx shadcn@latest add @sekei/shad-fx
npx shadcn@latest add @sekei/shad-fx-dither @sekei/shad-fx-fire

An effect on its own has nothing to draw on, so always take a renderer with it.

Nothing to configure. @sekei is in the shadcn registry directory, so the CLI resolves it and writes the registries entry into your components.json itself. To pin it yourself, by hand or in package.json — the CLI reads both:

{
  "registries": {
    "@sekei": "https://www.sekei.xyz/registry/{name}.json"
  }
}

Files land under components/shad-fx/ and hooks/, following your components.json aliases: renderers in dither/, effects in effects/. With the full library, import everything from @/components/shad-fx. With a renderer and a few effects, import from @/components/shad-fx/dither and @/components/shad-fx/effects/<name>.

If the namespace ever fails to resolve, the CLI can read the repo directly: prefix any item with sekeidesign/shad-fx/.

Usage

To have an agent set effects up for you, install the agent skills. One covers placement, the stable-reference rule, anchors and cost; the other writes new effects.

npx skills add sekeidesign/shad-fx

The canvas fills its nearest positioned ancestor, so give the parent relative.

import { DitherCanvas, fire } from "@/components/shad-fx";
import { useMemo } from "react";

export function Card() {
  const effect = useMemo(() => fire({ colors: ["#e5343a", "#f05100", "#fcbb00"] }), []);

  return (
    <div className="relative overflow-hidden rounded-lg">
      <DitherCanvas effect={effect} />
      <p className="relative">Burning</p>
    </div>
  );
}

Build the effect once. A new effect reference restarts the simulation — the canvas and its observer survive, but particles and heat fields reset. Use useMemo with the options in the dependency array, or module scope when the options are constant.

The element is aria-hidden and pointer-events-none: it is decoration, and never the only carrier of meaning.

Effects

To write an effect this set doesn't cover, have an agent do it with the agent skills. They cover the FxEffect contract, the Surface an effect paints into, reduced motion and parking.

npx skills add sekeidesign/shad-fx

Every effect is a factory returning an FxEffect, and every option is optional. The same effect runs on any renderer. RgbInput is a hex string or an [r, g, b] tuple. Where a count is given at full intensity, it scales down as the effect eases out.

origin and target take an Anchor: an [x, y] pair in 0–1 of the box, or a getter, which is re-read every frame — so an effect can follow something that moves without being rebuilt and losing what it has already simulated. Drag the dot in the playground above to see it.

Agent skills

Two skills, installed together, for an agent working in a project that uses shad-fx.

npx skills add sekeidesign/shad-fx

Reduced motion

The canvas reads prefers-reduced-motion through useSyncExternalStore, so it is correct on the server and updates when the setting changes. Under reduce, each effect paints one settled frame and stops: fire is pre-warmed and still, rings sit at three fixed radii, rain and snow hang mid-fall, particles are dropped. Nothing animates and the frame loop parks.

Cost

The engine runs requestAnimationFrame only while something is changing, and stops once the eased intensity has settled and the effect reports idle(). An inactive effect costs nothing. Each frame is one putImageData over a grid capped at 640×400 cells, not a fillRect per cell.

Credit

The ordered-dither rendering here, meaning the low-resolution backing canvas scaled up pixelated, the Bayer threshold matrix, and filling every cell at one of two alpha tiers rather than leaving holes, derives from dither-kit under the MIT licence. The effects, the painter, the frame loop and the reduced-motion handling are not.