UI / Layouts

CardList

Filterable card list layout with built-in grid and row stack view switching.

Lugia V

SITSilver Tempest#186#186SIRNMNMHOLOHolofoil

$214.75

▲5.4%

M Venusaur EX

EVOXY - Evolutions#100#100URLPLPHOLOHolofoil

$27.97

▲2.16%

Pikachu

MEWScarlet & Violet 151#173#173IRNMNMREVReverse Holofoil

$31.40

▲2.4%

1"use client";2 3import { useMemo, useState } from "react";4import { CardList } from "@cardspark/ui/layouts";5 6const cards = [7  {8    id: "sit-186",9    name: "Lugia V",10    set: "Silver Tempest",11    setCode: "SIT",12    number: "186/195",13    rarity: "Special Illustration Rare",14    condition: "Near Mint",15    marketValue: "$214.75",16    delta: "+5.4%",17    imageUrl: "https://images.pokemontcg.io/swsh12/186_hires.png"18  },19  {20    id: "evo-100",21    name: "M Venusaur EX",22    set: "XY - Evolutions",23    setCode: "EVO",24    number: "100/108",25    rarity: "Ultra Rare",26    condition: "Lightly Played",27    marketValue: "$27.97",28    delta: "+2.16%",29    imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"30  },31  {32    id: "mew-173",33    name: "Pikachu",34    set: "Scarlet & Violet 151",35    setCode: "MEW",36    number: "173/165",37    rarity: "Illustration Rare",38    condition: "Near Mint",39    finish: "Reverse Holofoil",40    marketValue: "$31.40",41    delta: "+2.4%",42    imageUrl: "https://images.pokemontcg.io/sv3pt5/173_hires.png"43  }44];45 46function getCardFilterValue(card, filterId) {47  switch (filterId) {48    case "set":49      return card.set;50    case "condition":51      return card.condition;52    case "rarity":53      return card.rarity;54    case "finish":55      return card.finish;56    default:57      return undefined;58  }59}60 61export function CollectionBrowserDemo() {62  const [filters, setFilters] = useState([63    {64      id: "set",65      label: "Set",66      value: "All Sets",67      options: ["All Sets", "Scarlet & Violet 151", "Silver Tempest", "XY - Evolutions"]68    },69    {70      id: "condition",71      label: "Condition",72      value: "All Conditions",73      options: ["All Conditions", "Near Mint", "Lightly Played"]74    },75    {76      id: "rarity",77      label: "Rarity",78      value: "All Rarities",79      options: ["All Rarities", "Illustration Rare", "Special Illustration Rare", "Ultra Rare"]80    },81    {82      id: "finish",83      label: "Finish",84      value: "All Finishes",85      options: ["All Finishes", "Holofoil", "Reverse Holofoil"]86    }87  ]);88 89  const visibleCards = useMemo(() => {90    return cards.filter((card) =>91      filters.every((filter) => filter.value.startsWith("All ") || getCardFilterValue(card, filter.id) === filter.value)92    );93  }, [filters]);94 95  return (96    <CardList97      cards={visibleCards}98      filters={filters}99      onFilterChange={(id, selection) => {100        if (typeof selection !== "string") return;101 102        setFilters((currentFilters) =>103          currentFilters.map((filter) => (filter.id === id ? { ...filter, value: selection } : filter))104        );105      }}106      format="market"107      gridColumns={3}108    />109  );110}

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 CardList from its package entry point.

CardListDemo.tsx

1"use client";2 3import { useMemo, useState } from "react";4import { CardList } from "@cardspark/ui/layouts";5 6const cards = [7  {8    id: "sit-186",9    name: "Lugia V",10    set: "Silver Tempest",11    setCode: "SIT",12    number: "186/195",13    rarity: "Special Illustration Rare",14    condition: "Near Mint",15    marketValue: "$214.75",16    delta: "+5.4%",17    imageUrl: "https://images.pokemontcg.io/swsh12/186_hires.png"18  },19  {20    id: "evo-100",21    name: "M Venusaur EX",22    set: "XY - Evolutions",23    setCode: "EVO",24    number: "100/108",25    rarity: "Ultra Rare",26    condition: "Lightly Played",27    marketValue: "$27.97",28    delta: "+2.16%",29    imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"30  },31  {32    id: "mew-173",33    name: "Pikachu",34    set: "Scarlet & Violet 151",35    setCode: "MEW",36    number: "173/165",37    rarity: "Illustration Rare",38    condition: "Near Mint",39    finish: "Reverse Holofoil",40    marketValue: "$31.40",41    delta: "+2.4%",42    imageUrl: "https://images.pokemontcg.io/sv3pt5/173_hires.png"43  }44];45 46function getCardFilterValue(card, filterId) {47  switch (filterId) {48    case "set":49      return card.set;50    case "condition":51      return card.condition;52    case "rarity":53      return card.rarity;54    case "finish":55      return card.finish;56    default:57      return undefined;58  }59}60 61export function CollectionBrowserDemo() {62  const [filters, setFilters] = useState([63    {64      id: "set",65      label: "Set",66      value: "All Sets",67      options: ["All Sets", "Scarlet & Violet 151", "Silver Tempest", "XY - Evolutions"]68    },69    {70      id: "condition",71      label: "Condition",72      value: "All Conditions",73      options: ["All Conditions", "Near Mint", "Lightly Played"]74    },75    {76      id: "rarity",77      label: "Rarity",78      value: "All Rarities",79      options: ["All Rarities", "Illustration Rare", "Special Illustration Rare", "Ultra Rare"]80    },81    {82      id: "finish",83      label: "Finish",84      value: "All Finishes",85      options: ["All Finishes", "Holofoil", "Reverse Holofoil"]86    }87  ]);88 89  const visibleCards = useMemo(() => {90    return cards.filter((card) =>91      filters.every((filter) => filter.value.startsWith("All ") || getCardFilterValue(card, filter.id) === filter.value)92    );93  }, [filters]);94 95  return (96    <CardList97      cards={visibleCards}98      filters={filters}99      onFilterChange={(id, selection) => {100        if (typeof selection !== "string") return;101 102        setFilters((currentFilters) =>103          currentFilters.map((filter) => (filter.id === id ? { ...filter, value: selection } : filter))104        );105      }}106      format="market"107      gridColumns={3}108    />109  );110}

Usage

CardListDemo.tsx

1"use client";2 3import { useMemo, useState } from "react";4import { CardList } from "@cardspark/ui/layouts";5 6const cards = [7  {8    id: "sit-186",9    name: "Lugia V",10    set: "Silver Tempest",11    setCode: "SIT",12    number: "186/195",13    rarity: "Special Illustration Rare",14    condition: "Near Mint",15    marketValue: "$214.75",16    delta: "+5.4%",17    imageUrl: "https://images.pokemontcg.io/swsh12/186_hires.png"18  },19  {20    id: "evo-100",21    name: "M Venusaur EX",22    set: "XY - Evolutions",23    setCode: "EVO",24    number: "100/108",25    rarity: "Ultra Rare",26    condition: "Lightly Played",27    marketValue: "$27.97",28    delta: "+2.16%",29    imageUrl: "https://images.pokemontcg.io/xy12/100_hires.png"30  },31  {32    id: "mew-173",33    name: "Pikachu",34    set: "Scarlet & Violet 151",35    setCode: "MEW",36    number: "173/165",37    rarity: "Illustration Rare",38    condition: "Near Mint",39    finish: "Reverse Holofoil",40    marketValue: "$31.40",41    delta: "+2.4%",42    imageUrl: "https://images.pokemontcg.io/sv3pt5/173_hires.png"43  }44];45 46function getCardFilterValue(card, filterId) {47  switch (filterId) {48    case "set":49      return card.set;50    case "condition":51      return card.condition;52    case "rarity":53      return card.rarity;54    case "finish":55      return card.finish;56    default:57      return undefined;58  }59}60 61export function CollectionBrowserDemo() {62  const [filters, setFilters] = useState([63    {64      id: "set",65      label: "Set",66      value: "All Sets",67      options: ["All Sets", "Scarlet & Violet 151", "Silver Tempest", "XY - Evolutions"]68    },69    {70      id: "condition",71      label: "Condition",72      value: "All Conditions",73      options: ["All Conditions", "Near Mint", "Lightly Played"]74    },75    {76      id: "rarity",77      label: "Rarity",78      value: "All Rarities",79      options: ["All Rarities", "Illustration Rare", "Special Illustration Rare", "Ultra Rare"]80    },81    {82      id: "finish",83      label: "Finish",84      value: "All Finishes",85      options: ["All Finishes", "Holofoil", "Reverse Holofoil"]86    }87  ]);88 89  const visibleCards = useMemo(() => {90    return cards.filter((card) =>91      filters.every((filter) => filter.value.startsWith("All ") || getCardFilterValue(card, filter.id) === filter.value)92    );93  }, [filters]);94 95  return (96    <CardList97      cards={visibleCards}98      filters={filters}99      onFilterChange={(id, selection) => {100        if (typeof selection !== "string") return;101 102        setFilters((currentFilters) =>103          currentFilters.map((filter) => (filter.id === id ? { ...filter, value: selection } : filter))104        );105      }}106      format="market"107      gridColumns={3}108    />109  );110}

Composition

Use CardList when a collection, set, or search page needs shared filters plus a switchable card grid or row stack.

1CollectionView2├── parent-owned query, sort, and filter state3└── CardList4    ├── toolbar5    │   ├── FilterBar6    │   └── grid / rows view toggle7    ├── CardGrid8    │   └── CardTile items9    └── CardStack10        └── CardRow items

Keep searching, sorting, pagination, loading, and empty-data decisions in the parent; CardList owns the display shell, empty-state slot, and optional view toggle.

Features

Composes FilterBar with CardGrid and CardStack for collection and set list screens.
Uses view, defaultView, and onViewChange for controlled or uncontrolled grid and row-stack switching.
Uses canonical card ids for default keys, forwards section props and refs, and accepts custom tile and row renderers.

API Reference

Prop	Type	Default	Description
`cards`	`TradingCardData[]`	-	Canonical card records with stable ids, rendered as CardTile items or CardRow items.
`filters`	`FilterBarItem[]`	`[]`	Filter definitions passed to the embedded FilterBar.
`onFilterChange`	`(id: string, selection: string \| string[]) => void`	-	Forwards embedded FilterBar changes with the active item's selection shape.
`filterActions`	`ReactNode`	-	Extra action content rendered beside the list view toggle.
`format`	`"market" \| "collection"`	`"market"`	Card presentation format passed to the default CardTile and CardRow renderers.
`view`	`"grid" \| "stack"`	-	Controlled active list presentation.
`defaultView`	`"grid" \| "stack"`	`"stack"`	Initial list presentation when view is uncontrolled.
`onViewChange`	`(view: CardListView) => void`	-	Callback fired when the grid or row-stack view changes.
`showViewToggle`	`boolean`	`true`	Controls whether CardList renders the grid and rows toggle.
`gridColumns`	`2 \| 3 \| 4`	`auto-fit`	Fixed grid column count passed to the embedded CardGrid.
`onCardClick`	`(card: TradingCardData, index: number, event: MouseEvent<HTMLElement>) => void`	-	Callback fired with the card, position, and native click event.
`getCardKey`	`(card: TradingCardData, index: number) => Key`	`card.id`	Custom key resolver for cards rendered by the list.
`renderTile`	`(card: TradingCardData, index: number) => ReactNode`	-	Custom renderer used instead of the default CardTile in grid view.
`renderRow`	`(card: TradingCardData, index: number) => ReactNode`	-	Custom renderer used instead of the default CardRow in row-stack view.
`tileProps`	`Omit<CardTileProps, "card" \| "format">`	-	Props spread into the default CardTile renderer.
`rowProps`	`Omit<CardRowProps, "card" \| "format">`	-	Props spread into the default CardRow renderer.
`emptyState`	`ReactNode`	`<p>No cards found.</p>`	Content shown when the card array is empty after parent filtering.