cards-css

Framework-agnostic holographic trading-card effect — tilt, shine, glare and fourteen foils (from the classic holo to aurora, gold, oilslick and mosaic) that react to pointer and gyroscope, with procedurally code-generated textures. No runtime dependencies.

Live demo → — move the pointer across a card, or tilt your phone, to see the foil shift.

Install

npm install @kongyo2/cards-css

Quick start

import { createHoloCard } from "@kongyo2/cards-css";
import "@kongyo2/cards-css/styles.css";

const card = createHoloCard({
  image: "/cards/phoenix.png",
  imageAlt: "Phoenix",
  effect: "holo",
});

document.querySelector("#stage").append(card.element);

createHoloCard builds the full element for you. To enhance markup you already have on the page (it must contain the .holo-card__rotator structure), use attachHoloCard(element, options) instead.

Effects

Set via the effect option (or card.setEffect(...) at runtime). The full list is exported as HOLO_EFFECTS for building pickers:

| Effect | Description | | ---------- | ------------------------------------------------------------------ | | none | Tilt, shine and glare only — no foil | | holo | Rainbow holographic foil | | reverse | Reverse-line holographic foil | | cosmos | Galaxy / cosmos foil (procedural — needs textureSeed) | | glitter | Glitter / sparkle foil (procedural — needs textureSeed) | | aurora | Northern-lights ribbons drifting across the card | | rainbow | Pastel rainbow wash with sparkle flecks (secret-rare style) | | gold | Molten gold foil with a hard specular sweep | | prism | Prismatic conic facets fanning around the parallax point | | radiant | Criss-cross radiant lines with white hatching | | crystal | Sharp crystalline shards gliding at independent speeds | | metal | Brushed-metal sheen with an anisotropic highlight | | oilslick | Oil-film interference rings with a moiré swirl | | sunburst | Coloured rays bursting from the pointer | | mosaic | Holographic mosaic tiles flipping as the card tilts |

rainbow and gold additionally layer the procedural glitter / grain textures when a textureSeed is provided, and degrade gracefully without one.

Options

| Option | Type | Default | Notes | | ----------------- | --------- | -------- | -------------------------------------------------- | | image | string | — | Front image source (required for createHoloCard) | | imageAlt | string | "" | Alt text for the front image | | back / backAlt| string | — | Optional card-back image and its alt text | | className | string | — | Extra class names for the root element | | effect | HoloEffect | "none" | One of the effects above | | interactive | boolean | true | React to pointer move | | activateOnClick | boolean | false | Click (or focus + Enter/Space) to pop the card into a centered showcase | | gyroscope | boolean \| GyroscopeOptions | true | Tilt to device orientation while active; pass an object to tune rangeX / rangeY / sensitivity / invertX / invertY | | showcase | boolean \| ShowcaseOptions | false | Auto-animate once on mount; pass an object to tune delay / duration / loop / speed / intensity / spring. Skipped under prefers-reduced-motion unless respectReducedMotion: false | | glow | string | — | CSS color for the card glow | | aspectRatio | number | — | Card aspect ratio (width / height) | | textureSeed | number | — | Seed for the generated cosmos / glitter textures (and the cosmos background placement, so a seeded card is fully deterministic); without it those two foils render without their procedural layers | | mask | string \| MaskOptions | — | Mask URL, or { image, size, position, repeat, mode } — mode: "card" clips the whole card into the mask silhouette | | foil | string | — | URL for a custom foil overlay | | palette | PaletteOptions | — | Foil colour theming: a preset (rainbow / gold / aurora / ruby / sapphire / mono) and/or custom sunpillars / spectrum / cosmos colour stops plus edge / back / glow | | glare | GlareOptions | — | Custom dynamic glare: a full image, or compose the pointer-tracking gradient from shape / extent / size / stops, plus blend / opacity | | depth | boolean \| DepthOptions | — | Foil 3D depth / extrusion: true for defaults, or tune strength / perspective / shadow / layerScale | | physics | PhysicsOptions | — | Interaction tuning: maxTilt / maxTiltX / maxTiltY, parallax, glareRange, returnDelay, and per-target spring tuning (interactSpring / popoverSpring / snapSpring / springs) | | visual | VisualOptions | — | Foil multipliers (brightness / contrast / saturate / glareOpacity / shineOpacity) and lineSpace / lineAngle / glitterSize / imageFit | | layers | HoloLayerOptions[] | — | Extra stacked layers between artwork and foil, each with image / content, blend, opacity, parallax, mask | | vars | Record<string, string \| number> | — | Arbitrary CSS custom properties on the root, for content linkage |

createHoloCard additionally accepts content and overlay (a Node or (doc) => Node) for free-form front and foreground content — name plates, badges, live data — plus overlayInteractive to let the overlay receive pointer events.

Asymmetric springs

Every spring tuning accepts an axes map for independent per-component physics, so a card can snap horizontally while easing vertically:

createHoloCard({
  image: "/cards/phoenix.png",
  effect: "holo",
  physics: { springs: { rotate: { axes: { x: { stiffness: 0.12 }, y: { stiffness: 0.04 } } } } },
});

Content linkage

While interacting, the card publishes its state as CSS custom properties on the root — --pointer-x, --pointer-y, --pointer-dx / --pointer-dy (signed, −1…1), --tilt-x / --tilt-y (degrees), --pointer-from-center and --card-active — so custom content / overlay / layers can parallax, glow or react in lockstep with the foil.

API

• createHoloCard(options) → HoloCard — builds the element (image required).
• attachHoloCard(element, options?) → HoloCard — wraps existing markup.
• HOLO_EFFECTS — every built-in effect name (none first), for pickers / cycling.
• HoloCard
  • element — the root HTMLElement to mount.
  • active / interacting — state getters.
  • front — the .holo-card__front element (or null), for appending content.
  • activate() / deactivate() — pop the card in / out of showcase.
  • setEffect(effect) — swap the foil at runtime.
  • setVisual(visual) / setVars(vars) — update visual controls / CSS variables at runtime.
  • setPalette(palette) — recolour the foil / swap themes at runtime.
  • setGlare(glare) — update the dynamic glare at runtime.
  • setDepth(depth) — toggle or tune the 3D depth at runtime (false disables it).
  • setGyroscope(gyroscope) — update gyroscope tuning at runtime.
  • addLayer(options) — insert an extra layer between artwork and foil, returns the element.
  • destroy() — remove listeners and timers, and clear the interaction state (classes, inline variables) from the element.

On iOS, gyroscope access needs a one-time permission prompt triggered by a user gesture — call requestOrientationPermission() (exported) from a click/tap handler.

License

MIT © kongyo2