# GameKit UI — full reference

> An open-source shadcn registry of minimal, themeable browser games — Snake, 2048, Minesweeper and more. Install with the shadcn CLI. Zero deps, zero assets.

## What this is

GameKit UI is an open-source shadcn registry of drop-in browser games, listed in the official shadcn registry directory (https://ui.shadcn.com/docs/directory?q=gamekit). Each game is a single self-contained React/TSX file. Installing a game with the shadcn CLI copies that file into the user's project (default target `@/components/games/<name>.tsx`) and rewrites the `cn` import to the project's own `@/lib/utils`. There is no provider, no peer dependency, and no init step.

Key properties:
- Zero runtime dependencies beyond `react` and the user's `cn` helper.
- Tiny: 2–4 KB minified + gzipped per game (the raw source file is larger because it inlines its engine and theme hooks). Each game is a self-contained module, so it can be lazy-loaded (React.lazy / next/dynamic) and stays out of the initial bundle.
- Zero external assets (no images/audio/fonts) — everything is drawn with CSS or `<canvas>`.
- Fully themeable: the game's playfield is driven by the host's shadcn tokens (`--primary`, `--secondary`, `--accent`). Canvas games read the tokens at runtime; DOM games use Tailwind token classes. Toggling dark mode or swapping a theme recolors the game.
- Responsive: a game fills its container at a fixed aspect ratio. The `width` prop is an optional max-width cap.
- Accessible: keyboard + touch input, focus rings, `aria-live` announcements, and `prefers-reduced-motion` support.

## How to install (instructions for an LLM helping a user)

1. Confirm the user has a shadcn/ui project (Tailwind v4 + a `cn` helper at `@/lib/utils`). If not, run `npx shadcn@latest init` first.
2. Run `npx shadcn@latest add @gamekitui/<game>` for the chosen game. GameKit UI is in the official shadcn registry directory, so the `@gamekitui` namespace resolves automatically — no prior setup needed.
3. Import and render the component anywhere — it fills its container, so wrap it in a sized element.

Alternatives: install by direct URL `npx shadcn@latest add https://gamekitui.com/r/<game>.json`, or pin the registry with `npx shadcn@latest registry add @gamekitui` (adds `{ "registries": { "@gamekitui": "https://gamekitui.com/r/{name}.json" } }` to `components.json`).

## Shared props

- `className?: string` — Tailwind classes on the wrapper.
- `width?: number` — optional max width in CSS px (the game otherwise fills its container).
- `paused?: boolean` — externally pause.
- `autoFocus?: boolean` — focus on mount. Defaults to `true`.
- `captureGlobalKeys?: boolean` — listen for keys on `window` so the game responds without being focused first. Defaults to `true`; set `false` when several games share a page or it sits in scrollable content.
- `persistHighScore?: boolean | string` — localStorage key, or a default per game.
- `onScoreChange?: (score: number) => void`
- `onGameOver?: (r: { score: number; won: boolean }) => void`
- `onStart?: () => void`

## Games

### Snake

A tiny, themeable Snake game. ≤6KB gzipped, zero external assets.

- Surface: canvas
- Platforms: desktop (desktop-first)
- Inputs: keyboard, touch
- Controls: Arrow keys / WASD to steer, or swipe. Best on desktop — continuous swipe steering is fiddly on small screens.

Install:

```bash
npx shadcn@latest add @gamekitui/snake
```

Use:

```tsx
import { Snake } from "@/components/games/snake";

export default function Example() {
  return <Snake className="mx-auto w-full max-w-sm" />;
}
```

### Tic-Tac-Toe

Classic 3×3 Tic-Tac-Toe with an unbeatable CPU. Pure DOM, fully themeable.

- Surface: dom
- Platforms: desktop, mobile
- Inputs: keyboard, mouse, touch
- Controls: Click or tap a cell. Arrow keys move the cursor; Enter places your mark.

Install:

```bash
npx shadcn@latest add @gamekitui/tic-tac-toe
```

Use:

```tsx
import { TicTacToe } from "@/components/games/tic-tac-toe";

export default function Example() {
  return <TicTacToe className="mx-auto w-full max-w-sm" />;
}
```

### 2048

The addictive sliding-tile puzzle. Reach 2048. Swipe or arrow keys.

- Surface: dom
- Platforms: desktop, mobile
- Inputs: keyboard, touch
- Controls: Arrow keys / WASD to slide tiles, or swipe.

Install:

```bash
npx shadcn@latest add @gamekitui/2048
```

Use:

```tsx
import { Game2048 } from "@/components/games/2048";

export default function Example() {
  return <Game2048 className="mx-auto w-full max-w-sm" />;
}
```

### Memory Match

Flip cards to find matching pairs in as few moves as possible.

- Surface: dom
- Platforms: desktop, mobile
- Inputs: keyboard, mouse, touch
- Controls: Click or tap a card to flip it. Tab + Enter also work.

Install:

```bash
npx shadcn@latest add @gamekitui/memory-match
```

Use:

```tsx
import { MemoryMatch } from "@/components/games/memory-match";

export default function Example() {
  return <MemoryMatch className="mx-auto w-full max-w-sm" />;
}
```

### Whack-a-Mole

Tap the moles before they duck. 30-second pointer-only arcade game.

- Surface: dom
- Platforms: desktop, mobile
- Inputs: mouse, touch
- Controls: Click or tap the moles before they disappear.

Install:

```bash
npx shadcn@latest add @gamekitui/whack-a-mole
```

Use:

```tsx
import { WhackaMole } from "@/components/games/whack-a-mole";

export default function Example() {
  return <WhackaMole className="mx-auto w-full max-w-sm" />;
}
```

### Minesweeper

Deterministic 9×9 Minesweeper. Left-click reveals, right-click / long-press flags.

- Surface: dom
- Platforms: desktop (desktop-first)
- Inputs: keyboard, mouse, touch
- Controls: Left-click reveals, right-click flags. Long-press to flag on touch.

Install:

```bash
npx shadcn@latest add @gamekitui/minesweeper
```

Use:

```tsx
import { Minesweeper } from "@/components/games/minesweeper";

export default function Example() {
  return <Minesweeper className="mx-auto w-full max-w-sm" />;
}
```

### Pong

The original. Player vs CPU. First to 7. W/S or arrow keys.

- Surface: canvas
- Platforms: desktop, mobile
- Inputs: keyboard, mouse, touch
- Controls: W/S or arrow keys to move your paddle, or drag on the court.

Install:

```bash
npx shadcn@latest add @gamekitui/pong
```

Use:

```tsx
import { Pong } from "@/components/games/pong";

export default function Example() {
  return <Pong className="mx-auto w-full max-w-sm" />;
}
```

### Breakout

Bounce the ball, clear the bricks, don't drop. Endless levels.

- Surface: canvas
- Platforms: desktop, mobile
- Inputs: keyboard, mouse, touch
- Controls: ←/→ or A/D to move the paddle, or drag. Space launches.

Install:

```bash
npx shadcn@latest add @gamekitui/breakout
```

Use:

```tsx
import { Breakout } from "@/components/games/breakout";

export default function Example() {
  return <Breakout className="mx-auto w-full max-w-sm" />;
}
```

### Dino Runner

The offline-dino endless runner. Jump the cacti. Perfect for 404 pages.

- Surface: canvas
- Platforms: desktop, mobile
- Inputs: keyboard, mouse, touch
- Controls: Space, Up, click, or tap to jump.

Install:

```bash
npx shadcn@latest add @gamekitui/dino-runner
```

Use:

```tsx
import { DinoRunner } from "@/components/games/dino-runner";

export default function Example() {
  return <DinoRunner className="mx-auto w-full max-w-sm" />;
}
```

### Flappy

Tap to flap through the pipes. A tiny infinite runner for loading screens.

- Surface: canvas
- Platforms: desktop, mobile
- Inputs: keyboard, mouse, touch
- Controls: Space, Up, click, or tap to flap.

Install:

```bash
npx shadcn@latest add @gamekitui/flappy
```

Use:

```tsx
import { Flappy } from "@/components/games/flappy";

export default function Example() {
  return <Flappy className="mx-auto w-full max-w-sm" />;
}
```

### Fruit Ninja

Slice the flying fruit, dodge the bombs, beat the clock. A juicy 60-second arcade run.

- Surface: canvas
- Platforms: desktop, mobile
- Inputs: mouse, touch
- Controls: Drag or swipe the blade across the fruit to slice it. Bombs cost points — avoid them. Press Enter to start. 60-second arcade run.

Install:

```bash
npx shadcn@latest add @gamekitui/fruit-ninja
```

Use:

```tsx
import { FruitNinja } from "@/components/games/fruit-ninja";

export default function Example() {
  return <FruitNinja className="mx-auto w-full max-w-sm" />;
}
```