# Effects library

Past the reveal's own show there is a library of 64 effects: particles, light, waves, and effects that act on the whole stage. Each is one name. Play one on its own, stack several at the same moment, or hand an opener a [plan](https://bettertyped.github.io/react-cards-opening/docs/effects/plans/) that says which tier gets what.

> Live preview: see it play at https://bettertyped.github.io/react-cards-opening/docs/effects/library/
>
> Every effect, on a button. Pick a tier to change the colour they play in.

## A package of its own

The effects live in `@react-cards-opening/effects`. The ui package brings it along and carries its stylesheet, so with the card components installed there is nothing to add, and everything on this page can be imported from either. For effects without cards, install it alone: nothing in it knows what a card is.

```bash
pnpm add @react-cards-opening/effects gsap
```

```tsx
import "@react-cards-opening/effects/styles.css";
```

## Playing one

```tsx
import { EffectLayer, type EffectLayerHandle } from "@react-cards-opening/effects";

const layer = useRef<EffectLayerHandle>(null);

<EffectLayer handle={layer} />;

layer.current?.play("shockwave");
layer.current?.play(["flash", "nova", "embers"], { at: cardElement, tone: "#f5c451" });
```

An effect is drawn for a card 300 pixels wide and scaled to whatever it celebrates, so the same `sparks` fits a badge and a full-screen reveal. It takes its colour from the `tone` you give it. [EffectLayer](https://bettertyped.github.io/react-cards-opening/docs/components/effect-layer/) has every option.

## Particles (24)

Drawn on one canvas a layer, so a hundred of them cost about as much as one. Lights add up where they cross on a dark page and are painted on a light one.

| Effect | Name | What it looks like | Seconds |
| --- | --- | --- | --- |
| Sparks | `sparks` | A ring of lit squares thrown hard and slowing fast, the way the card's own burst does. | 1.3 |
| Confetti | `confetti` | Paper thrown up from behind the card. It flutters, shows its darker side, and falls. | 3 |
| Embers | `embers` | Small hot lights lifting off the card, drifting and flickering out on the way up. | 3.4 |
| Stardust | `stardust` | Four-pointed stars easing outward and twinkling as they slow. | 2.6 |
| Pixels | `pixels` | Hard square pixels on a grid, blown out and dropped. Nothing is smoothed. | 1.6 |
| Shards | `shards` | Splinters of glass with one lit facet each, spinning as they fall. | 1.7 |
| Fountain | `fountain` | A jet of lights from the top of the card that climbs, spreads and rains back down. | 2.6 |
| Bubbles | `bubbles` | Thin rings with a glint, wobbling up past the card and popping. | 3.2 |
| Snow | `snow` | Soft flakes falling across the whole stage, near ones larger and faster than far ones. | 5 |
| Petals | `petals` | Petals let go from above the card, turning over and swinging side to side as they come down. | 4 |
| Comets | `comets` | A handful of bright heads with tapering tails, fired outward. | 1.1 |
| Spiral | `spiral` | Three arms of light winding out from behind the card like a small galaxy. | 2.2 |
| Fireflies | `fireflies` | Slow lights wandering around the card, each pulsing at its own pace. | 3.8 |
| Rain of light | `rain` | Fast thin streaks falling past the card at a slant. | 2.2 |
| Orbit | `orbit` | Lights circling the card on a tilted ring, tightening as they fade. | 2.6 |
| Implosion | `implosion` | Streaks drawn in from all around to the card's middle. A charge, best before something louder. | 0.95 |
| Smoke | `smoke` | Soft puffs in the tier's colour swelling and thinning out behind the card. | 2.4 |
| Coins | `coins` | Coins tossed up from the card, flashing as they turn and dropping under their own weight. | 2.2 |
| Fireworks | `fireworks` | Three shells going off around the card one after another, each a round burst that hangs and falls. | 2.6 |
| Glitter | `glitter` | Stars that light and go out where they stand, all around the card. | 2.4 |
| Pixel ring | `ring-of-pixels` | A shockwave drawn in pixels: one clean ring of squares that widens and thins. | 1 |
| Dust | `dust` | A low cloud kicked out sideways from the card's foot, as if it had landed hard. | 1.5 |
| Leaves | `leaves` | Leaves lifted off the card's edge by an updraft, turning over as they climb and drift apart. | 2.8 |
| Flames | `flames` | The card burns: fire climbs its sides, closes over the top of it and tears off, with sparks riding the heat. | 3 |

## Light (16)

Elements the stylesheet draws and a timeline moves: wheels of rays, beams, flashes and glows.

| Effect | Name | What it looks like | Seconds |
| --- | --- | --- | --- |
| Rays | `rays` | The wheel of rays a loud card opens behind itself, turning slowly. | 2.6 |
| Beams | `beams` | A few broad, soft shafts of light sweeping past each other in two layers. | 3 |
| Halo | `halo` | A soft ring of light around the card that breathes a few times and lets go. | 2.4 |
| Flash | `flash` | The whole stage goes white at the card and falls away through the tier's colour. | 0.85 |
| Lens flare | `flare` | A wide streak through a hot core, with two ghosts sliding out along it, as through a lens. | 1.5 |
| Spotlight | `spotlight` | A cone of light from the top of the stage that finds the card, sways and settles on it. | 2.6 |
| Aurora | `aurora` | Three blurred bands in the tier's colour and the accent, drifting across each other. | 3.2 |
| Sunburst | `sunburst` | Needle-thin spikes shot outward once, like light off a blade. | 0.9 |
| Bloom | `bloom` | One big soft swell of light from the middle that floods and fades. | 1.6 |
| Starburst | `starburst` | A four-pointed star that snaps open, turns a little and closes: the glint on something precious. | 0.95 |
| Pillar | `pillar` | A column of light through the card from the top of the stage to the bottom, the beam over rare loot. | 2 |
| Lightning | `lightning` | Jagged bolts out of the card that strike, vanish and strike again along new paths. | 0.62 |
| Rim light | `rim` | The card's own outline, lit hot from behind, pulsing twice. | 1.6 |
| Frost | `frost` | A six-armed ice crystal that grows out from behind the card, turns a notch and melts away. | 2 |
| Sigil | `sigil` | A circle of power drawn behind the card: two rings, a six-pointed star and a second seal turning against it. | 2.6 |
| Cracks | `cracks` | The air around the card splits: glowing fractures race outward, fork, and burn out slowly. | 1.9 |

## Waves (11)

One shape getting bigger: rings, ripples and outlines thrown out from the card, or drawn in to it.

| Effect | Name | What it looks like | Seconds |
| --- | --- | --- | --- |
| Shockwave | `shockwave` | One thick ring thrown out from the card, thinning as it goes. | 1.1 |
| Ripples | `ripples` | Three thin rings one after another, as on water. | 1.7 |
| Pulse | `pulse` | A filled disc with a bright edge that swells out and thins to nothing. | 0.9 |
| Sonar | `sonar` | A sweeping arm inside a fine ring, with two pings going out from the middle. | 2.1 |
| Hex wave | `hex` | A six-sided outline that opens, turns a notch and fades, with a second one behind it. | 1.2 |
| Diamond wave | `diamond` | The same, cut as a diamond: sharper, and it turns a quarter as it goes. | 1.2 |
| Ground slam | `slam` | A ring that spreads flat along the floor under the card, as if it had been dropped there. | 0.9 |
| Converge | `converge` | Rings closing in on the card from outside. A wind-up, the opposite of a shockwave. | 1 |
| Heatwave | `heatwave` | A ring with no colour of its own: it bends and brightens whatever it passes over. | 1 |
| Card echo | `echo` | The card's own outline, three times over, each one larger and fainter than the last. | 1.4 |
| Nova | `nova` | A disc of white light that bursts, hollows from the middle and leaves as a ring. | 1 |

## Screen (13)

These act on the whole stage: they move it, wash it, or lay something across all of it.

| Effect | Name | What it looks like | Seconds |
| --- | --- | --- | --- |
| Shake | `shake` | A short, sharp side-to-side jolt of the stage. | 0.42 |
| Quake | `quake` | A longer rumble that throws the stage about in every direction and dies down. | 0.85 |
| Punch | `punch` | The stage jumps a few percent toward the viewer and springs back. | 0.55 |
| Vignette | `vignette` | The edges of the stage close in with the tier's colour and open again. | 1.5 |
| Tint | `tint` | The whole stage takes the tier's colour for a moment, as through tinted glass. | 0.85 |
| Scanlines | `scanlines` | Fine lines across the stage and one bright band that runs down through them. | 1.3 |
| Glitch | `glitch` | Torn bars of colour jumping across the stage while it skews, for half a second. | 0.5 |
| Chroma split | `chroma` | Two flashes, one in the tier's colour and one in the accent, thrown apart and pulled back into one. | 0.6 |
| Letterbox | `letterbox` | Two black bars slide in at the top and bottom, hold, and leave: the stage becomes a film for a moment. | 2.4 |
| Flicker | `flicker` | The lights cut out three times, each cut shorter than the last. | 0.42 |
| Speed lines | `speedlines` | Thin lines racing in from the edges toward the card, redrawn every few frames. | 0.8 |
| Impact frame | `negative` | Two frames of the stage in negative, the way a drawn impact is punctuated. | 0.26 |
| Focus pull | `focus` | The stage starts blurred and comes sharp, as a lens finding its subject. | 0.8 |

## Stacking

Effects are made to be played together. A good hit is usually three things at the same moment: something for the whole stage, a wave, and particles. `["flash", "shockwave", "sparks"]` is a rare card. `["negative", "nova", "pillar", "embers", "quake"]` is the one people screenshot. For a wind-up, play `implosion` or `converge` first and the hit after it with `delay`.

## An effect of your own

An effect is an object: a name, how long it plays, and a `play` that adds to a GSAP timeline. Two helpers do the drawing. `emit` lets particles go, and `part` puts an element on the stage, already centred and sized. Your effect goes anywhere a name does.

```ts
import { emit, part, playEffects, type Effect } from "@react-cards-opening/effects";

const hearts: Effect = {
  name: "hearts",
  kind: "particles",
  label: "Hearts",
  about: "Pink petals that rise instead of falling, over a soft ring.",
  seconds: 2.4,
  play: (stage, timeline) => {
    emit(stage, timeline, {
      count: 30,
      shape: "petal",
      colours: ["#fb7185", "#fda4af"],
      from: "edge",
      angle: [-Math.PI * 0.9, -Math.PI * 0.1],
      speed: [120, 380],
      gravity: -120,
      life: [1.4, 2.2],
      size: [8, 14],
      flip: [0.6, 1.4],
    });
    const ring = part(stage, "shockwave");
    timeline.fromTo(ring, { opacity: 1, scale: 0.2 }, { opacity: 0, scale: 3, duration: 0.9 }, 0);
  },
};

playEffects(layer, [hearts, "flash"]);
```

| Helper | What it does |
| --- | --- |
| `emit(stage, timeline, spec)` | Lets particles go at a moment of the effect. |
| `part(stage, name)` | Puts an element on the stage with the class `rco-fx-<name>`, centred on the effect. Pass `true` as a third argument for one that fills the stage. |
| `piece(parent, name)` | An element inside a part: a ring's second line, a flare's ghost. |
| `drawing(stage, name, { tag, count })` | An SVG outline that stays one line thick however far it is stretched. This is how the hex wave and the lightning are drawn. |
| `corners(sides)` | The points of a shape with that many sides, for a `drawing`. |
| `onEdge(angle, ratio)` | Where a line from the middle crosses the card's outline, for placing things on its edge. |
| `tint(colour, amount)`, `shade(colour, amount)` | A hex colour part of the way to white, or to black. |

```ts
import { corners, drawing, type Effect } from "@react-cards-opening/effects";

// A triangle thrown out from the card, drawn with the hex wave's own styles.
const triangle: Effect = {
  name: "triangle",
  kind: "wave",
  label: "Triangle",
  about: "Three sides, thrown out from the card.",
  seconds: 1,
  play: (stage, timeline) => {
    const [line] = drawing(stage, "hex", { tag: "polygon" });
    line.setAttribute("points", corners(3));
    timeline.fromTo(line.parentElement, { opacity: 1, scale: 0.3 }, { opacity: 0, scale: 3, duration: 1 }, 0);
  },
};
```

Particles come in eleven shapes: `square`, `dot`, `mote`, `star`, `streak`, `shard`, `flake`, `ring`, `petal`, `puff` and `coin`. Speeds are in pixels a second, angles in radians with zero pointing right, and `from: "edge"` starts each one on the card's outline, where it is seen from the first frame.

## Restyling one

Every part that is not a particle is an element with a class: `.rco-fx-shockwave`, `.rco-fx-rays`, `.rco-fx-pillar`. Each rule weighs one class, like the rest of the [stylesheet](https://bettertyped.github.io/react-cards-opening/docs/guides/styling/), so a rule of your own wins without a fight.

```css
/* A dashed shockwave. */
.rco-fx-shockwave {
  border-style: dashed;
}
```

## Related

- [Effect plans](https://bettertyped.github.io/react-cards-opening/docs/effects/plans/)
- [EffectLayer](https://bettertyped.github.io/react-cards-opening/docs/components/effect-layer/)
- [Effects](https://bettertyped.github.io/react-cards-opening/docs/effects/)
- [CardPack](https://bettertyped.github.io/react-cards-opening/docs/components/card-pack/)
- [Reduced motion](https://bettertyped.github.io/react-cards-opening/docs/core/reduced-motion/)

Source: https://bettertyped.github.io/react-cards-opening/docs/effects/library/