UI / Core

CardGrid

Responsive card gallery container for repeated CardTile children.

Venusaur ex

$76.40

MEW#198SIR(NM)

▲4.1%

Poliwrath

$15.72

MEW#176IR(LP)

▲1.8%

Pikachu

$22.18

MEW#173IR(NM)

▲2.6%

1import { CardGrid, CardTile } from "@cardspark/ui/core";2 3const cards = [4  {5    id: "mew-198",6    name: "Venusaur ex",7    set: "Scarlet & Violet 151",8    setCode: "MEW",9    number: "198/165",10    rarity: "Special Illustration Rare",11    condition: "Near Mint",12    marketValue: "$76.40",13    delta: "+4.1%",14    imageUrl: "https://images.pokemontcg.io/sv3pt5/198_hires.png",15    tone: "neutral"16  },17  {18    id: "mew-176",19    name: "Poliwrath",20    set: "Scarlet & Violet 151",21    setCode: "MEW",22    number: "176/165",23    rarity: "Illustration Rare",24    condition: "Lightly Played",25    marketValue: "$15.72",26    delta: "+1.8%",27    imageUrl: "https://images.pokemontcg.io/sv3pt5/176_hires.png",28    tone: "water"29  },30  {31    id: "mew-173",32    name: "Pikachu",33    set: "Scarlet & Violet 151",34    setCode: "MEW",35    number: "173/165",36    rarity: "Illustration Rare",37    condition: "Near Mint",38    marketValue: "$22.18",39    delta: "+2.6%",40    imageUrl: "https://images.pokemontcg.io/sv3pt5/173_hires.png",41    tone: "neutral"42  },43  {44    id: "mew-181",45    name: "Dragonair",46    set: "Scarlet & Violet 151",47    setCode: "MEW",48    number: "181/165",49    rarity: "Illustration Rare",50    condition: "Near Mint",51    marketValue: "$18.34",52    delta: "+1.2%",53    imageUrl: "https://images.pokemontcg.io/sv3pt5/181_hires.png",54    tone: "water"55  }56];57 58export function CardGridDemo() {59  return (60    <CardGrid columns={3}>61      {cards.map((card) => (62        <CardTile key={card.id} card={card} />63      ))}64    </CardGrid>65  );66}

Installation

Install the package.

npm install @cardspark/ui

Import the shared stylesheet layer near your app root.

app/layout.tsx

1import "@cardspark/ui/tokens.css";2import "@cardspark/ui/themes/basement.css";3import "@cardspark/ui/styles.css";

Import and render CardGrid from its package entry point.

CardGridDemo.tsx

1import { CardGrid, CardTile } from "@cardspark/ui/core";2 3const cards = [4  {5    id: "mew-198",6    name: "Venusaur ex",7    set: "Scarlet & Violet 151",8    setCode: "MEW",9    number: "198/165",10    rarity: "Special Illustration Rare",11    condition: "Near Mint",12    marketValue: "$76.40",13    delta: "+4.1%",14    imageUrl: "https://images.pokemontcg.io/sv3pt5/198_hires.png",15    tone: "neutral"16  },17  {18    id: "mew-176",19    name: "Poliwrath",20    set: "Scarlet & Violet 151",21    setCode: "MEW",22    number: "176/165",23    rarity: "Illustration Rare",24    condition: "Lightly Played",25    marketValue: "$15.72",26    delta: "+1.8%",27    imageUrl: "https://images.pokemontcg.io/sv3pt5/176_hires.png",28    tone: "water"29  },30  {31    id: "mew-173",32    name: "Pikachu",33    set: "Scarlet & Violet 151",34    setCode: "MEW",35    number: "173/165",36    rarity: "Illustration Rare",37    condition: "Near Mint",38    marketValue: "$22.18",39    delta: "+2.6%",40    imageUrl: "https://images.pokemontcg.io/sv3pt5/173_hires.png",41    tone: "neutral"42  },43  {44    id: "mew-181",45    name: "Dragonair",46    set: "Scarlet & Violet 151",47    setCode: "MEW",48    number: "181/165",49    rarity: "Illustration Rare",50    condition: "Near Mint",51    marketValue: "$18.34",52    delta: "+1.2%",53    imageUrl: "https://images.pokemontcg.io/sv3pt5/181_hires.png",54    tone: "water"55  }56];57 58export function CardGridDemo() {59  return (60    <CardGrid columns={3}>61      {cards.map((card) => (62        <CardTile key={card.id} card={card} />63      ))}64    </CardGrid>65  );66}

Usage

CardGridDemo.tsx

1import { CardGrid, CardTile } from "@cardspark/ui/core";2 3const cards = [4  {5    id: "mew-198",6    name: "Venusaur ex",7    set: "Scarlet & Violet 151",8    setCode: "MEW",9    number: "198/165",10    rarity: "Special Illustration Rare",11    condition: "Near Mint",12    marketValue: "$76.40",13    delta: "+4.1%",14    imageUrl: "https://images.pokemontcg.io/sv3pt5/198_hires.png",15    tone: "neutral"16  },17  {18    id: "mew-176",19    name: "Poliwrath",20    set: "Scarlet & Violet 151",21    setCode: "MEW",22    number: "176/165",23    rarity: "Illustration Rare",24    condition: "Lightly Played",25    marketValue: "$15.72",26    delta: "+1.8%",27    imageUrl: "https://images.pokemontcg.io/sv3pt5/176_hires.png",28    tone: "water"29  },30  {31    id: "mew-173",32    name: "Pikachu",33    set: "Scarlet & Violet 151",34    setCode: "MEW",35    number: "173/165",36    rarity: "Illustration Rare",37    condition: "Near Mint",38    marketValue: "$22.18",39    delta: "+2.6%",40    imageUrl: "https://images.pokemontcg.io/sv3pt5/173_hires.png",41    tone: "neutral"42  },43  {44    id: "mew-181",45    name: "Dragonair",46    set: "Scarlet & Violet 151",47    setCode: "MEW",48    number: "181/165",49    rarity: "Illustration Rare",50    condition: "Near Mint",51    marketValue: "$18.34",52    delta: "+1.2%",53    imageUrl: "https://images.pokemontcg.io/sv3pt5/181_hires.png",54    tone: "water"55  }56];57 58export function CardGridDemo() {59  return (60    <CardGrid columns={3}>61      {cards.map((card) => (62        <CardTile key={card.id} card={card} />63      ))}64    </CardGrid>65  );66}

Composition

Use this composition to build a complete card grid surface with filtering, sorting, and repeated cards.

1CardGridSurface2├── Header / result count3├── FilterBar4│   ├── Search5│   ├── Condition6│   ├── Rarity7│   └── Sort8└── CardGrid9    ├── CardTile10    │   ├── card art11    │   ├── name, set, number, and rarity12    │   └── value, delta, and condition13    └── Empty state / loading state

Keep filtering and sorting state outside the grid, pass the resulting card array into CardGrid, and let CardTile own each card's display details.

Features

Accepts children so CardTile or another card-shaped item owns artwork, metadata, value movement, condition, and fallback content.
Uses the columns prop for auto-fit by default or fixed 2, 3, and 4 column gallery modes when a surface needs tighter control.
Forwards its ref and native div props while search, filter, sort, loading, and empty states stay outside the grid API.

API Reference

Prop	Type	Default	Description
`children`	`ReactNode`	-	`CardTile` children to arrange.
`columns`	`2 \| 3 \| 4`	`auto-fit`	Sets a fixed column count.