Dither Icons

Dithered, animated SVG icons for React.

81 original icons in dither, solid, and outline. Each has its own animation: a bell swings, a download arrow lands, a lock resists a shake. Use the React components or export individual SVGs. The latest four Cognimated reader-control icons are unreleased additions in this checkout.

Get started · Documentation · For AI agents · Contributing · MIT license

Features

• Three materials. Dither, solid and outline share the same original geometry in a 24 × 24 viewBox.
• Individual motion. Every icon has an authored gesture. Semantic parts move together; the grain stays attached to its surface.
• Playback. Hover, keyboard focus and tap play once. React playback finishes after you leave and ignores overlapping triggers.
• Accessible by default. Reduced motion is respected. Decorative icons stay out of the accessibility tree; meaningful images can have a title.
• Color. Icons inherit currentColor. The gallery includes eight palettes with light and dark variants.
• React or SVG. Typed components, forwarded SVG refs and standalone SVG export. No separate stylesheet or animation dependency.
• Context for your agent. An exact export manifest, integration guide and labeled visual references ship alongside the code.

Browse the machine-readable collection or the individual motion catalog.

Get started

Node.js 22+ is recommended for development. React 18+ is the library's only peer dependency.

git clone https://github.com/vijayksingh/dither-icons.git
cd dither-icons
npm ci
npm run dev

Open http://127.0.0.1:4192 to explore the gallery. Hover or tap a preview to play it; select the name to open its page. Customize the material, color and size, then copy React or download an SVG.

| Local page | What you can do | | --- | --- | | / | Search and explore the collection | | /icons/download | Preview, inspect timing, copy source and export one icon | | /motion | Compare gestures, play at half speed and inspect individual frames | | /docs | Read installation, API, motion, accessibility and SVG guides | | /ai | Build integration instructions and download agent context |

Cmd/Ctrl-K searches pages and icons. / focuses the collection filter. Browser Back restores your filter, scroll position and focused icon.

Use in your React app

Install the package from npm:

npm install @unlocalhosted/dither-icons

Use with shadcn

Add the client-safe adapter from the public registry:

npx shadcn@latest add https://dithered.dev/r/dither-icon.json

This adds components/ui/dither-icon.tsx and installs the library dependency. Use any valid name from icons.json, or install directly from the GitHub registry source with npx shadcn@latest add vijayksingh/dither-icons/dither-icon.

Import a named component and put the action on a real control:

import { DownloadIcon } from '@unlocalhosted/dither-icons';

export function DownloadButton({ onDownload }: { onDownload: () => void }) {
  return (
    <button type="button" className="di-trigger" onClick={onDownload}>
      <DownloadIcon size={48} texture="dither" />
      <span>Download file</span>
    </button>
  );
}

di-trigger lets the whole control's hover, focus or tap trigger the icon. The visible text names this button; use aria-label for an icon-only control. Your application owns the action, loading state and result. The gesture never substitutes for confirmation that an operation succeeded.

Navigation and workspace

ArrowLeftIcon (Back), HistoryIcon, PanelLeftCloseIcon (Collapse Panel), and ZoomOutIcon are available in 0.2.0 and later. Their motions express navigation intent; the host owns routing, explorer state, history selection, and map magnification.

Cognimated reader controls — unreleased

DragHandleIcon, SkipBlockIcon, CollapseRailIcon, and HeadphonesIcon are source additions for moving the control tray, skipping an article block, collapsing the rail and headphone audio output. Review the Cognimated reader controls set in the local Motion studio. Each has an individual animation and all three materials. See control mapping and checks/feedback status. User visual approval and Cognimated integration remain pending; these four are not available from the current published package.

Cognimated reader — unreleased

ReadingFocusIcon, StartAtTextIcon, ListenIcon, and ReadAloudIcon are available in this source checkout and local builds. Inspect the Cognimated reader set in the motion studio. Reading Focus advances a window within a timer; Start at Text places a caret; Listen emits sound from a page; Read Aloud receives speech before text responds. The host retains timer state, seeking, audio playback, microphone permission, and recognition-backed progress. No Cognimated call sites are integrated by this batch. See control mapping and review evidence.

Lock and Unlock

UnlockIcon is available in 0.2.0 and later. Both icons share a housing, but their resting states stay distinct with motion disabled. Select them from your application's real state:

import { LockIcon, UnlockIcon } from '@unlocalhosted/dither-icons';

export function AccessState({ locked }: { locked: boolean }) {
  const Icon = locked ? LockIcon : UnlockIcon;
  return <Icon size={24} texture="outline" title={locked ? 'Locked' : 'Unlocked'} />;
}

Choose a material

| Material | Suggested use | | --- | --- | | dither | Expressive detail at 48px and above | | solid | Clear silhouettes in compact 16–24px controls | | outline | A lighter presence in toolbars and navigation |

The texture sits inside a smooth vector silhouette. Color comes from the surrounding interface; check contrast at the size you actually use.

Component API

All components accept ordinary SVG props and forward an SVG ref.

| Prop | Default | Behavior | | --- | --- | --- | | size | 24 | Width and height; number or CSS-compatible string | | texture | dither | dither, solid or outline | | animate | true | Enable interaction-triggered motion | | active | false | Play when this becomes true; reset false before a later trigger | | replayKey | 0 | Change the value to request another playback | | speed | 1 | Positive playback rate; 0.5 is half speed | | progress | — | Pause at a normalized frame from 0 to 1; omit to resume interaction | | title | — | Name a meaningful SVG image; otherwise it is decorative |

For runtime selection, use DitherIcon with a valid name from icons.json. Invalid names throw a descriptive error. See the complete React guide for examples.

Motion and SVG behavior

React uses the native Web Animations API. Each gesture returns to rest, completes after pointer departure, and cancels on unmount, motion-off or a reduced-motion preference change. animate={false} takes precedence over active playback.

Standalone SVGs contain the same tracks compiled to CSS, including reduced-motion rules. Inline the complete SVG, including its styles, masks and internal definitions, for hover playback. An <img> embedding is static. CSS hover playback ends when hover ends; use React when the gesture should finish after pointer departure. Keep internal IDs unique when combining exported SVGs in one document.

ESM and TypeScript declarations are included. Named exports currently share the complete geometry catalog; per-icon bundle splitting is not implemented.

Documentation and AI context

| Guide | Contents | | --- | --- | | Introduction | First icon, materials and library behavior | | Installation | npm package, React environments and SVG use | | React API | Props, named exports, dynamic selection and replay | | Motion | Semantic gestures, triggers and frame inspection | | Accessibility | Labels, keyboard interaction, state and reduced motion | | SVG export | Complete markup, styling and playback limitations |

Give your coding agent AI.md and icons.json. Together they describe the real exports, their meaning and the integration contract. For more context, use the complete text guide, material sheet and labeled collection.

The local site also serves /llms.txt and an instruction builder at /ai. Download the files when working with a remote agent that cannot reach your local preview.

Development

npm run typecheck     # TypeScript
npm test              # Geometry, choreography, exports and documentation checks
npm run build         # React package, downloadable tarball and public site
npm run generate:docs # Regenerate guides, manifest and visual references
npm run verify:deployment # Verify the public domain, assets and sharing metadata

| Directory | Purpose | | --- | --- | | src/ | Original artwork, React components and motion engine | | src/motions/ | Individually authored icon timelines | | demo/ | Gallery, icon pages, motion studio and documentation UI | | demo/content/ | Shared source for web guides and generated Markdown | | public/ | Agent context, static references and downloadable guides | | docs/ | Design principles, individual reviews and browser evidence | | tests/ | Geometry, motion, accessibility and export contracts |

dist/ contains the built React package; site-dist/ contains the built public site. Build and pack regenerate the documentation from the real exports. Edit demo/content/docs.ts and demo/content/agent.ts, then regenerate instead of hand-editing generated files.

Cloudflare Pages serves the generated route directories and provides its native SPA fallback. Do not add a catch-all rewrite that replaces route-specific HTML. Stable vX.Y.Z tags publish the React package to npm and deploy the same release to Cloudflare. See the release and agent runbook and Cloudflare deployment checks. Main pushes run CI without publishing.

Contributing

Contributions are welcome. Start with CONTRIBUTING.md and the motion principles.

For a new icon, begin with an actual interface action. Define its meaning, the silhouette that must remain readable, and the parts that cause each other to move. Refine one gesture before repeating an approach across the library. Include real browser evidence for visual or motion changes.

Report a bug or propose an icon.

Credits and license

Created by Vijay Singh / Unlocalhosted. Find me on Twitter / X and LinkedIn. The public browsing experience takes inspiration from lucide-animated and transitions.dev. The icon geometry and implementation are original; reference branding, assets and source are not included.

MIT — free to use, modify and distribute, including in commercial projects. Retain the license notice.

Social previews

The production build generates 1200 × 630 PNG previews and crawler-readable HTML for the home page, guides, motion studio, AI page, and all 81 icons. Share an icon URL after its release to show that icon in the preview. Open Graph and Twitter card metadata are present in the initial HTML; crawlers do not need JavaScript.

The canonical origin defaults to https://dithered.dev. To build for another origin:

SITE_URL=https://your-domain.example npm run build

Deploy the complete site-dist/ directory, including route directories and og/. Existing files must take precedence over the SPA fallback. Social networks can cache previews; publishing a build does not invalidate their caches. No deployment is performed by npm run build.

npm run generate:social regenerates just the images from the original artwork. Their bundled DM Sans font is licensed under the SIL Open Font License. Preview metadata follows the Open Graph specification.