CARDSPARK_UI
Install

UI / Core

CardArt

Card art surface with automatic rarity-driven tilt, glow, specular, and fallback treatment.

M Venusaur EX card
import { CardArt } from "@cardspark/ui/core"; const card = {  name: "M Venusaur EX",  rarity: "Ultra Rare",  imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"}; export function CardArtDemo() {  return (    <CardArt      src={card.imageUrl}      alt="M Venusaur EX Pokemon card"      fallbackLabel={card.name}      rarity={card.rarity}    />  );}

Installation

Install the package.

npm install @cardspark/ui

Import the shared stylesheet layer near your app root.

app/layout.tsx
import "@cardspark/ui/tokens.css";import "@cardspark/ui/themes/basement.css";import "@cardspark/ui/styles.css";

Import and render CardArt from its package entry point.

CardArtDemo.tsx
import { CardArt } from "@cardspark/ui/core"; const card = {  name: "M Venusaur EX",  rarity: "Ultra Rare",  imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"}; export function CardArtDemo() {  return (    <CardArt      src={card.imageUrl}      alt="M Venusaur EX Pokemon card"      fallbackLabel={card.name}      rarity={card.rarity}    />  );}

Usage

CardArtDemo.tsx
import { CardArt } from "@cardspark/ui/core"; const card = {  name: "M Venusaur EX",  rarity: "Ultra Rare",  imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"}; export function CardArtDemo() {  return (    <CardArt      src={card.imageUrl}      alt="M Venusaur EX Pokemon card"      fallbackLabel={card.name}      rarity={card.rarity}    />  );}

Composition

Use CardArt as the card-art media node inside detail pages, media panels, rows, thumbnails, or focused card previews.

MediaSurface└── CardArt    ├── src / alt / fallbackLabel    ├── load placeholder and reveal state    ├── rarity-driven effects    └── optional back face

Provide meaningful alt text and a fallback label so image failures still identify the card.

Features

  • Renders src and alt as the focused card artwork surface with package tilt, glow, and specular behavior.
  • Uses fallbackLabel when artwork is unavailable so media slots still identify the card.
  • Forwards its ref and native div props; rarity, showGlow, showSpecular, specularEffect, and showBackFace tune visual effects.

Examples

Loading

Use the automatic loading state for image fetches, or force it when rendering a deterministic placeholder.

M Venusaur EX card
import { CardArt } from "@cardspark/ui/core"; const card = {  name: "M Venusaur EX",  rarity: "Ultra Rare",  imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"}; export function CardArtLoadingDemo() {  return (    <CardArt      src={card.imageUrl}      alt="M Venusaur EX Pokemon card"      fallbackLabel={card.name}      rarity={card.rarity}      loadState="loading"    />  );}

Transition

When the image resolves, CardArt flips the placeholder 180 degrees on the vertical axis to reveal the loaded artwork.

M Venusaur EX card
import { CardArt } from "@cardspark/ui/core"; const card = {  name: "M Venusaur EX",  rarity: "Ultra Rare",  imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"}; export function CardArtTransitionDemo() {  return (    <CardArt      src={card.imageUrl}      alt="M Venusaur EX Pokemon card"      fallbackLabel={card.name}      rarity={card.rarity}      loadState="transitioning"    />  );}

Loaded

Loaded art keeps the same rarity-driven glow, holo specular, and pointer tilt behavior.

M Venusaur EX card
import { CardArt } from "@cardspark/ui/core"; const card = {  name: "M Venusaur EX",  rarity: "Ultra Rare",  imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"}; export function CardArtLoadedDemo() {  return (    <CardArt      src={card.imageUrl}      alt="M Venusaur EX Pokemon card"      fallbackLabel={card.name}      rarity={card.rarity}      loadState="loaded"    />  );}

API Reference

PropTypeDefaultDescription
srcstring-Card artwork URL.
altstring-Accessible card artwork description.
fallbackLabelstring-Text shown when artwork is missing.
raritystring-Card rarity used to resolve automatic glow and specular effects.
loadState"auto" | "loading" | "transitioning" | "loaded""auto"Controls the image load placeholder and 180-degree reveal state.
showGlowboolean | "auto""auto"Controls the blurred artwork glow.
showSpecularboolean | "auto""auto"Controls the interactive foil/specular overlay.
specularEffect"auto" | "plain" | "holo""auto"Chooses the specular treatment. Auto uses holo for high-rarity and holo card rarities.
showBackFacebooleanfalseRenders the card back face for detail spin treatments.
tiltMultipliernumber1Scales the pointer-driven card tilt amount.