# Pixel Icon

> 300 original retro desktop icons, drawn on a 32-pixel grid with detailed silhouettes, beveled edges, and theme colors.

- Name: `pixel-icon`
- Status: beta
- Categories: media, display
- File: the install writes `pixel-icon.tsx` to your `ui` alias, `@/components/ui` by default.
- Gallery: https://arbokui.com/components/pixel-icon
- Registry item: https://arbokui.com/r/pixel-icon.json

## Install

1. Add the registry to `components.json`. Do this first, once:

   ```bash
   npx shadcn@latest registry add "@arbokui=https://arbokui.com/r/{name}.json"
   ```

   The command writes this entry. You can also add it by hand:

   ```json
   {
     "registries": {
       "@arbokui": "https://arbokui.com/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@arbokui` in a public list that Arbokui does not control.

2. Add the theme once per app. It replaces your color tokens with ones checked for contrast:

   ```bash
   npx shadcn@latest add @arbokui/theme
   ```

3. Add the component:

   ```bash
   npx shadcn@latest add @arbokui/pixel-icon
   ```

## Use it for

- Retro interfaces, file browsers, playful empty states, and illustrated navigation.
- Use pixelIconCatalog for all 300 names and their 15 categories. Each icon has distinct artwork; directional and file-state variants are included.
- Use sm at 32px, md at 64px, or lg at 96px to preserve whole pixels.
- Use getPixelIconSvg(name, palette) to export a standalone SVG. The palette has 14 entries, including transparent at index 0. Resolve pixelIconPaints in the scoped theme before exporting; pixelIconTokens lists their source tokens. The Library block handles this conversion.
- The complete set ships together. Use the Pixel Icon Library block to search, copy, or download individual SVGs and the full ZIP.

## Avoid it for

- Dense 16px toolbars: use Icon instead.
- Color alone to communicate status. Pair each illustration with a label.
- Importing the collection solely for one tiny icon when bundle size is critical.

## Props

- `palette`: `PixelIconPalette`. Optional 14-entry artwork palette, including transparency at index 0. Missing entries use the theme.
- `name`: `PixelIconName`. Default `"desktop-computer"`. One of the 300 names in pixelIconCatalog.
- `size`: `"sm" | "md" | "lg"`. Default `"md"`. 32, 64, or 96 pixels. The underlying grid is always 32 × 32.
- `title`: `string`. Accessible name for a meaningful standalone icon. Omit when neighboring text names it.
- `className`: `string`. Classes on the SVG; later classes win. Prefer whole multiples of 32px.

## Accessibility

- Decorative icons are hidden from screen readers. With title, the SVG is an image with that accessible name.
- SVGs do not take keyboard focus. A surrounding icon-only action still needs its own accessible label.
- Artwork follows the theme. Decorative shading is not a text-contrast claim.

## Examples

### With a visible label

```tsx
<div className="flex items-center gap-3"><PixelIcon name="folder-open" size="sm" /><span>Project files</span></div>
```

### Standalone illustration

```tsx
<PixelIcon name="desktop-computer" size="lg" title="Desktop computer" />
```

### All available names

```tsx
import { PixelIcon, pixelIconCatalog } from "@/components/ui/pixel-icon";

<div className="flex flex-wrap gap-4">{pixelIconCatalog.map(({ name }) => <PixelIcon key={name} name={name} title={name.replaceAll("-", " ")} />)}</div>
```