pokemon-card-3d

Pokemon TCG card component with authentic 3D interactions and foil/holographic effects, built for React.

Features

• 🎴 Authentic 3D tilt effect on mouse/touch interaction
• ✨ 15+ foil effects: Holo, Cosmos, Radiant, Rainbow, Secret Rare, V Full Art, Shiny Vault…
• 📐 Fully size-adaptive — set any width, height is automatic
• 🎯 Self-contained state — drop in anywhere, no external state management needed
• 🔮 Showcase mode — auto-rotating animation on mount
• 💪 TypeScript first

Install

npm install pokemon-card-3d @react-spring/web
# or
pnpm add pokemon-card-3d @react-spring/web

Peer dependencies: react >=18, react-dom >=18, @react-spring/web >=10

Quick Start

import { Card } from "pokemon-card-3d";
import "pokemon-card-3d/style";

export default function App() {
  return (
    <Card
      id="swsh1-25"
      name="Pikachu"
      number="25"
      set="swsh1"
      types={["lightning"]}
      rarity="rare holo"
      img="https://images.pokemontcg.io/swsh1/25_hires.png"
    />
  );
}

Props

| Prop | Type | Default | Description | |:------------ |:---------------------- |:-------------- |:-------------------------------------------------------- | | img | string | required | Front face image URL | | id | string | "" | Unique card ID (e.g. "swsh1-25") | | name | string | "" | Card name (used for aria-label) | | number | string \| number | "" | Card number within its set | | set | string | "" | Set code (e.g. "swsh1") | | types | string \| string[] | "" | Element types — controls glow color | | subtypes | string \| string[] | "basic" | Subtypes (e.g. ["Stage 2"]) | | supertype | string | "pokémon" | "pokémon" | "trainer" | "energy" | | rarity | string | "common" | Card rarity — drives the foil effect (see table below) | | back | string | Official back | Back face image URL | | foil | string | "" | Foil overlay image URL (for masked foil cards) | | mask | string | "" | Mask image URL (for selective foil regions) | | width | number | 250 | Card width in pixels — height auto from aspect ratio | | showcase | boolean | false | Auto-rotate animation on mount | | className | string | "" | Extra class names on the root element | | onActivate | () => void | — | Fired when card is tapped/clicked to expand | | onDeactivate | () => void | — | Fired when card collapses |

Rarity Values & Effects

| rarity value | Effect | |:----------------------------- |:------------------------- | | "common" / "uncommon" | Glare only | | "rare holo" | Rainbow holo bars | | "rare holo cosmos" | Galaxy/cosmos texture | | "amazing rare" | Glitter + foil mask | | "radiant rare" | Criss-cross sparkle | | "*reverse holo" | Reverse foil (any ending in reverse holo) | | "rare ultra" | V Full Art sunpillar | | "trainer gallery rare holo" | Metallic iridescent | | "rare secret" | Gold glitter | | "rare shiny" / "rare shiny v" / "rare shiny vmax" | Shiny Vault |

Size Examples

{/* Small card */}
<Card img="..." rarity="rare holo" width={180} />

{/* Default */}
<Card img="..." rarity="rare holo" width={250} />

{/* Large display */}
<Card img="..." rarity="rare holo" width={400} />

{/* Full-width responsive — wrap in a container */}
<div style={{ width: "100%", maxWidth: 320 }}>
  <Card img="..." rarity="rare holo" width={320} />
</div>

Custom Image Assets

The foil effects for Cosmos Holo, Secret Rare, Amazing Rare, and Trainer Full Art require texture images. By default these are loaded from the jsDelivr CDN.

To use your own hosted images, override the CSS custom properties before importing the component styles:

:root {
  --pkm-img-glitter:       url("/assets/glitter.png");
  --pkm-img-grain:         url("/assets/grain.webp");
  --pkm-img-cosmos-bottom: url("/assets/cosmos-bottom.png");
  --pkm-img-cosmos-middle: url("/assets/cosmos-middle-trans.png");
  --pkm-img-cosmos-top:    url("/assets/cosmos-top-trans.png");
  --pkm-img-trainer-bg:    url("/assets/trainerbg.png");
  --pkm-img-geometric:     url("/assets/geometric.png");
}

Showcase Mode

<Card
  img="https://images.pokemontcg.io/swsh1/25_hires.png"
  rarity="rare holo cosmos"
  showcase   {/* auto-rotates for 4 seconds on mount */}
  width={300}
/>

Callbacks

<Card
  img="..."
  rarity="rare ultra"
  onActivate={() => console.log("card expanded!")}
  onDeactivate={() => console.log("card collapsed!")}
/>

License

MIT