# Dither Icon

> 60 original monochrome icons with optional shifting dither dots, transparent backgrounds, and theme colors.

- Name: `dither-icon`
- Status: beta
- Categories: media, display
- File: the install writes `dither-icon.tsx` to your `ui` alias, `@/components/ui` by default.
- Other registry items: `@arbokui/dither`. The install adds them.
- Gallery: https://arbokui.com/components/dither-icon
- Registry item: https://arbokui.com/r/dither-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/dither-icon
   ```

## Use it for

- Illustrated navigation, empty states, and retro interfaces.
- Use ditherIconNames to list all 60 icons, covering everyday controls, files, devices, objects, and nature.
- Use animated to swap interior dots while outlines, detail lines, and the ink count in each tile stay fixed. Thin solid strokes stay still.
- Provide a pause control for looping decorative animation. Use paused on one icon, or set --dither-icon-play-state: paused on a container to freeze a collection.
- Use 32, 64, or 96px to keep the 32-pixel grid sharp.
- getDitherIconSvg(name, fill) returns a still standalone SVG; fill accepts a hex color or defaults to currentColor. Inline SVG inherits text color; a downloaded file uses the viewer's default ink.

## Avoid it for

- Small toolbar actions below 32px: use Icon or Solid Icon instead.
- Using texture or color alone to communicate status. Add a visible label.

## Props

- `texture`: `"flat" | "dither" | "gradient" | "grain"`. dither draws the shape as dots, denser toward the bottom right, gradient as color that deepens the same way, and grain as still specks over a light wash. Hover fills each in to the solid shape, and shows a flat icon's dots. Left out, the icon follows the Texture around it, and is flat with none.
- `animated`: `boolean`. Default `false`. Dithered, loops four crisp dot patterns on the theme's pulse duration. No translation, scaling, or fading.
- `paused`: `boolean`. Default `false`. Freeze on the current animation frame. Has no effect on a still icon.
- `fill`: `string`. Optional SVG artwork fill. Use a chosen hex color to override the tone.
- `name`: `DitherIconName`. Default `"folder"`. One of the 60 names in ditherIconNames.
- `size`: `"sm" | "md" | "lg"`. Default `"md"`. 32, 64, or 96 pixels.
- `tone`: `"neutral" | "brand" | "danger" | "success" | "warning"`. Default `"neutral"`. The theme color used for every ink pixel.
- `title`: `string`. Accessible name for a standalone icon. Omit beside equivalent text.
- `className`: `string`. Classes merged last on the SVG.

## Accessibility

- Decorative icons are hidden from screen readers. A title makes the SVG a named image.
- The SVG does not take keyboard focus. Icon-only actions need their own accessible label.
- Reduced motion and the theme's Motion Off setting show the first frame without animating. Animation does not announce individual frames.
- Dithered shading is decorative; it is not a contrast guarantee.

## Examples

### Animated texture

```tsx
<DitherIcon name="planet" texture="dither" animated title="Planet" />
```

### With a label

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

### Standalone image

```tsx
<DitherIcon name="trophy" size="lg" tone="brand" title="Trophy" />
```