The best way to build your own Pokédex app.
A production-ready, domain-driven UI kit built on top of shadcn/ui, designed to handle complex Pokémon data with speed, consistency, and full customization.
This is not a Pokédex. It is the foundation for building Pokémon applications.
Most Pokémon projects start the same way: fetching data from PokéAPI, building cards, rendering sprites, wiring up search, and repeating the same UI patterns across every app. As projects grow, you end up rewriting the same components and maintaining inconsistent interfaces across codebases.
CompoDex solves this with a set of composable, Pokémon-aware primitives:
- 🎯 Pokémon-First — Components understand domain concepts: types, sprites, IDs, and base stats.
- 🧩 Composition — Small, reusable building blocks with a shared, predictable API.
- 📖 Open Code — You install the real source. Read it, customize it, own it.
- 🛠️ Developer Experience — TypeScript-first, consistent patterns, Tailwind-ready.
- 🚀 Production Ready — Built for real apps, not just demos.
CompoDex is distributed as a shadcn registry. Add any component to your own project with a single command — the source lands directly in your codebase.
# Add the Pokémon type color theme (recommended first)
pnpm dlx shadcn@latest add @compodex/pokemon-type-colors
# Add components
pnpm dlx shadcn@latest add @compodex/badge-type
pnpm dlx shadcn@latest add @compodex/pokemon-sprite
pnpm dlx shadcn@latest add @compodex/pokemon-card
pnpm dlx shadcn@latest add @compodex/pokemon-stat
pnpm dlx shadcn@latest add @compodex/pokedexComponents that depend on the theme (badges, cards, stats) pull
@compodex/pokemon-type-colorsautomatically.
import { PokemonBadgeType } from "@/components/compodex/ui/badge-type";
import { PokemonCard } from "@/components/compodex/ui/pokemon-card";
export function Charizard() {
return (
<PokemonCard type="fire" secondary="flying">
<PokemonBadgeType type="fire">Fire</PokemonBadgeType>
<PokemonBadgeType type="flying" variant="soft">Flying</PokemonBadgeType>
</PokemonCard>
);
}| Component | Description |
|---|---|
| Pokemon Type Colors | A theme that adds --color-type-* tokens for all 20+ Pokémon types, generating utilities like bg-type-fire, text-type-grass, border-type-water. |
| Badge Type | A badge displaying a Pokémon type with per-type colors and solid, soft, outline, and ghost variants. |
| Pokemon Card | A card surface tinted by primary/secondary types, with gradient dual-type backgrounds and a mega variant. |
| Pokemon Sprite | An avatar-style sprite with image, fallback, badge, group, and group-count parts. |
| Pokemon Stat | Base-stat rows (HP, Attack, Defense…) on shadcn Field + Progress, with per-stat colors and composable parts. |
| Pokedex | Controllable Pokédex primitives: search, domain filters, incremental pagination, renderItem collections, empty state, and counts. Bring your own data. |
See dual-type card variants
The Pokedex primitive composes everything — search, type filters, pagination and your own data fetching — into a full collection experience.
This repository is both the component library and its documentation site (Next.js 16 + Turbopack + MDX).
- Node.js 18.18+
- pnpm
pnpm install # install dependencies
pnpm dev # start dev server at http://localhost:3000| Script | Description |
|---|---|
pnpm dev |
Development server (Turbopack). |
pnpm build |
Production build. |
pnpm start |
Serve the production build. |
pnpm lint |
Lint with ESLint. |
pnpm typecheck |
Type-check with TypeScript. |
pnpm format |
Format with Prettier. |
pnpm registry:build |
Build the shadcn registry from registry.json. |
compo-dex/
├── app/(www)/ # Docs site + Pokédex demo routes
│ ├── docs/ # MDX-powered documentation
│ └── pokedex/ # Live Pokédex demo
├── components/
│ ├── compodex/ui/ # 📦 The published components (the registry source)
│ ├── compodex/blocks/ # Higher-level composed blocks
│ ├── demo/ # Demos rendered inside the docs
│ └── ui/ # Base shadcn/ui primitives
├── content/docs/ # MDX documentation content
├── lib/ # Registry, content & site configuration
├── public/r/ # Built registry JSON (served to shadcn CLI)
└── registry.json # Registry manifest (source of truth)
- Next.js 16 (App Router, Turbopack)
- React 19 & TypeScript
- Tailwind CSS 4 with
class-variance-authority - shadcn/ui registry distribution
- Radix UI / Base UI primitives
- Framer Motion for animation
- MDX for documentation
- pokenode-ts for PokéAPI typing
Contributions are welcome! To add or modify a component:
- Create the component in
components/compodex/ui/. - Register it in
registry.json. - Run
pnpm registry:buildto regeneratepublic/r/*.json. - Add documentation under
content/docs/components/.
Please run pnpm lint and pnpm typecheck before opening a PR.
The CompoDex source code is released under the MIT License.
"Pokémon" and all Pokémon character names are trademarks of Nintendo, Game Freak, and The Pokémon Company. CompoDex is an unofficial, fan-made project and is not affiliated with, sponsored by, or endorsed by any of them.
Pokémon sprites and official artwork displayed in the demo are sourced from PokéAPI and the PokeAPI/sprites repository. These assets are used solely for demonstration purposes and remain the property of their respective owners (Nintendo / Game Freak / The Pokémon Company).
CompoDex is built on top of: