# React Cards Opening

> React components and hooks for opening cards: a card that flies out, hums, flips and lands, a scan that hunts for it, and rarity effects up to a legendary foil.

react-cards-opening is two React packages on npm: @react-cards-opening/core holds the rules of a card opening with nothing drawn, and @react-cards-opening/ui draws it on GSAP timelines with one stylesheet and no CSS framework. Source: https://github.com/BetterTyped/react-cards-opening

## Get started

- [Introduction](https://bettertyped.github.io/react-cards-opening/docs/index.md): What react-cards-opening is: a headless core that holds the rules of opening cards, and a ui package that draws the reveal, from a hop to a legendary foil.
- [Installation](https://bettertyped.github.io/react-cards-opening/docs/installation/index.md): Install react-cards-opening with pnpm, npm, yarn or bun, import its one stylesheet, and check what it needs: React 18 or 19 and GSAP 3.13 or newer.
- [Your first opening](https://bettertyped.github.io/react-cards-opening/docs/first-opening/index.md): Open your first card in about twenty lines: describe the cards, keep track of which are opened, and render CardOpening with a button to leave from.
- [Theming](https://bettertyped.github.io/react-cards-opening/docs/theming/index.md): Theme a card opening with one of ten built-in themes in dark or light, a theme made from a single accent colour, or an object of your own colours.
- [Rarity tiers](https://bettertyped.github.io/react-cards-opening/docs/rarity-tiers/index.md): How rarity works in react-cards-opening: six default tiers from common to mythic, the weight that sets how often each comes up, and the show each one gets.

## Core

- [Core](https://bettertyped.github.io/react-cards-opening/docs/core/index.md): The headless half of react-cards-opening: the queue, the press rules, rarity tiers, seeded rolls and opened-card storage, with React as its only dependency.
- [useCardOpening](https://bettertyped.github.io/react-cards-opening/docs/core/use-card-opening/index.md): useCardOpening keeps the queue of a card opening and answers what a press on the card or the backdrop means at each moment. No animation, no markup.
- [useCardPack](https://bettertyped.github.io/react-cards-opening/docs/core/use-card-pack/index.md): useCardPack is the rules of a card pack as a React hook: sealed, dealt face down, each card turned over in any order, then done. Bring your own table.
- [useOpenedCards](https://bettertyped.github.io/react-cards-opening/docs/core/use-opened-cards/index.md): useOpenedCards remembers which cards were opened on this device in local storage, keyed by the deal, and keeps working when storage is blocked.
- [Rolls and odds](https://bettertyped.github.io/react-cards-opening/docs/core/rolls/index.md): Deal cards by rarity weight with rollCards, read each card's chance with chances, and make a roll repeatable on any device with a seed.
- [Show plan](https://bettertyped.github.io/react-cards-opening/docs/core/show-plan/index.md): showFor turns a tier's effect level into the plan of its reveal as plain data, and holdSeconds works out how long a card stays face up to be read.
- [Hiding places](https://bettertyped.github.io/react-cards-opening/docs/core/spots/index.md): pickSpot chooses a lit, free cell of a grid for a card to hide in, and useCardSpots remembers each card's cell so a replay reopens the same tiles.
- [Reduced motion](https://bettertyped.github.io/react-cards-opening/docs/core/reduced-motion/index.md): What a card opening does for someone whose system asks for reduced motion: no sweep, no shake, no legendary show, and every card still opens.

## Components

- [Components](https://bettertyped.github.io/react-cards-opening/docs/components/index.md): The components of @react-cards-opening/ui: a pack, a reel, a case and a hunt to open cards with, the reveal they share, and a library of effects.
- [CardPack](https://bettertyped.github.io/react-cards-opening/docs/components/card-pack/index.md): CardPack is a sealed pack of cards for React: press it and it bursts, deals its cards face down, and each one turns over on a press with its tier's show.
- [CardSpin](https://bettertyped.github.io/react-cards-opening/docs/components/card-spin/index.md): CardSpin is a case-opening reel for React: a strip of tiles races under a marker, slows, and stops on the card that was dealt, which then lifts out of it.
- [CardWheel](https://bettertyped.github.io/react-cards-opening/docs/components/card-wheel/index.md): CardWheel is a prize wheel for React: wedges in their tiers' colours spin under a pointer, slow, and stop on the card that was dealt, which lifts out of its wedge.
- [CardCase](https://bettertyped.github.io/react-cards-opening/docs/components/card-case/index.md): CardCase is a loot case for React: it shakes, the lid lifts, light pours out, and its cards come out one after another to land on a shelf under it.
- [CardHunt](https://bettertyped.github.io/react-cards-opening/docs/components/card-hunt/index.md): CardHunt is a grid with cards hidden in it, a button that scans for them, the reveal for each one found, and a list of finds that can be opened again.
- [CardOpening](https://bettertyped.github.io/react-cards-opening/docs/components/card-opening/index.md): CardOpening plays a card's reveal over the page: it leaves an element you name, turns over in the middle of the screen with its tier's show, and lands.
- [ScanGrid](https://bettertyped.github.io/react-cards-opening/docs/components/scan-grid/index.md): ScanGrid draws a grid of cells and the scan that hunts one down: a beam that sweeps and doubles back, a reticle that locks on, and a cell that cracks.
- [Card](https://bettertyped.github.io/react-cards-opening/docs/components/card/index.md): Card draws a card that is not being opened: for a collection, a shop or a list of pulls. Same face, same foil border and shine, drawn with CSS alone.
- [PixelGlyph](https://bettertyped.github.io/react-cards-opening/docs/components/pixel-glyph/index.md): PixelGlyph draws 9 by 9 pixel art from nine strings, in one colour. Twenty five glyphs ship with the library, and drawing your own means typing one out.
- [EffectLayer](https://bettertyped.github.io/react-cards-opening/docs/components/effect-layer/index.md): EffectLayer is a sheet you lay over any element to play the library's effects on it: a shockwave on a button, confetti over a page, a flash behind a card.

## Effects

- [Effects](https://bettertyped.github.io/react-cards-opening/docs/effects/index.md): A live gallery of every effect for card openings in React: six signature shows, two dozen combinations, and each effect on its own.
- [Effects library](https://bettertyped.github.io/react-cards-opening/docs/effects/library/index.md): 64 effects for card openings in React: particles, rays and flares, shockwaves, and screen effects like shake and glitch, each one name to play.
- [Effect plans](https://bettertyped.github.io/react-cards-opening/docs/effects/plans/index.md): Every rarity tier plays a show of its own as its card turns over, from a common's puff of dust to a mythic's cataclysm. See what is in each and change any of it.
- [Flight](https://bettertyped.github.io/react-cards-opening/docs/effects/flight/index.md): The first move of every reveal: the card lifts out of the element it was found in and flies to the middle of the screen, face down.
- [Hum](https://bettertyped.github.io/react-cards-opening/docs/effects/hum/index.md): The beat a face-down card holds before it turns: its edge lights up in its tier's colour, and it hops or shakes depending on how rare it is.
- [Flip](https://bettertyped.github.io/react-cards-opening/docs/effects/flip/index.md): The turn itself: the card straightens, rotates face up with a little overshoot, and its rows of text rise in one after another.
- [Burst](https://bettertyped.github.io/react-cards-opening/docs/effects/burst/index.md): Twenty two square particles in the tier's colour thrown outward from the card as it turns face up. Every tier gets it.
- [Rays](https://bettertyped.github.io/react-cards-opening/docs/effects/rays/index.md): A wheel of rays that opens behind a loud card as it turns and slowly rotates while the card is up. Epic and legendary tiers get it.
- [Flash](https://bettertyped.github.io/react-cards-opening/docs/effects/flash/index.md): A full-screen flash in the tier's colour the instant a legendary turns, and a softer one over the grid when a loud card is found.
- [Shockwaves](https://bettertyped.github.io/react-cards-opening/docs/effects/shockwaves/index.md): Two glowing rings that expand from a legendary card as it turns, one a fifth of a second behind the other.
- [Foil border](https://bettertyped.github.io/react-cards-opening/docs/effects/foil-border/index.md): A conic gradient that spins behind a legendary card's edge, in the theme's own legendary colour, never a fixed gold.
- [Shine](https://bettertyped.github.io/react-cards-opening/docs/effects/shine/index.md): A band of light that sweeps across a legendary card's face every couple of seconds, blended so it brightens what is under it.
- [Sparkles](https://bettertyped.github.io/react-cards-opening/docs/effects/sparkles/index.md): Sixteen small diamonds around a legendary card that blink on and off in a random order while it is face up.
- [Beam and lock](https://bettertyped.github.io/react-cards-opening/docs/effects/beam-and-lock/index.md): The scan's hunt: a beam sweeps the grid lighting each column, doubles back, and a reticle closes in on the cell that holds a card.
- [Crack](https://bettertyped.github.io/react-cards-opening/docs/effects/crack/index.md): The moment the scan lands: the cell flares in the card's colour, a ring rolls out, sparks fly, and a loud find shakes the whole grid.
- [Found pulse](https://bettertyped.github.io/react-cards-opening/docs/effects/found-pulse/index.md): What a grid looks like after the hunt: found cells breathe in their tier's colour, throw a spark now and then, and open their card on a press.

## Guides

- [Styling by hand](https://bettertyped.github.io/react-cards-opening/docs/guides/styling/index.md): Restyle any part of a card opening with Tailwind utilities or plain CSS: a classNames prop for every part and a stylesheet where every rule weighs one class.
- [Custom card face](https://bettertyped.github.io/react-cards-opening/docs/guides/custom-card-face/index.md): Replace the ready-made card face with your own: an image, stats, anything. Keep the rise-in animation with one class and size it so it scales with the card.
- [Custom tiers](https://bettertyped.github.io/react-cards-opening/docs/guides/custom-tiers/index.md): Define your own rarity tiers, three or seven of them, give each a colour on the theme, and pick the show each one gets with a single word.
- [Origin and landing](https://bettertyped.github.io/react-cards-opening/docs/guides/origin-and-landing/index.md): Tell a card where to come out of and where to go: a button, a pack, a slot in a collection. Play a timeline of your own before it leaves.
- [Keep opened cards](https://bettertyped.github.io/react-cards-opening/docs/guides/keep-opened-cards/index.md): Three ways to remember which cards were opened: local storage with useOpenedCards, your own state, or a server, written to from onOpen.
- [Your own UI on core](https://bettertyped.github.io/react-cards-opening/docs/guides/own-ui-on-core/index.md): Build a card reveal on @react-cards-opening/core alone: the rules from the hook, the look from your own markup, CSS or animation library.
- [Server rendering](https://bettertyped.github.io/react-cards-opening/docs/guides/server-rendering/index.md): Render react-cards-opening on a server: what is in the HTML, what waits for the browser, and how to avoid a flash for returning visitors.
- [Labels and translation](https://bettertyped.github.io/react-cards-opening/docs/guides/labels-and-translation/index.md): Change or translate every word a card hunt shows and every label a screen reader hears, through one labels prop with strings and functions.

## Examples

- [Examples](https://bettertyped.github.io/react-cards-opening/docs/examples/index.md): Complete, working card openings to copy: the full hunt as it runs in Hype Stack's Wrapped, a card opened from a button, and a collection that fills up.
- [Card hunt example](https://bettertyped.github.io/react-cards-opening/docs/examples/card-hunt/index.md): A complete card hunt in one file: five cards hidden in a grid, a scan that finds them, opened cards remembered on the device, and a replay.
- [Open from a button](https://bettertyped.github.io/react-cards-opening/docs/examples/open-from-a-button/index.md): The smallest working card opening: one button that deals a card by rarity weight and a reveal that flies out of it. About thirty lines.
- [Collection example](https://bettertyped.github.io/react-cards-opening/docs/examples/collection/index.md): A collection shelf where every card lies face down and opens where it lies: it lifts out of its place, turns over, and lands back face up.

## Optional

- [Every page in one file](https://bettertyped.github.io/react-cards-opening/llms-full.txt)