# SVG Icon Library

> Search and filter an SVG collection, preview icons, copy their markup, and download individual files or a prepared ZIP.

- Name: `svg-icon-library`
- Status: beta
- Categories: icons, assets, downloads
- Files: the install writes `svg-icon-library.tsx`, and any part files named `svg-icon-library-*.tsx`, to your `components` alias, `@/components` by default. Edit them freely. They are yours.
- Other registry items: `@txbrendan/accordion`, `@txbrendan/toast`, `@txbrendan/icon-color-picker`, `@txbrendan/button`, `@txbrendan/search-field`, `@txbrendan/select`, `@txbrendan/skeleton`. The install adds them.
- Gallery: https://txbrendan.dev/blocks/svg-icon-library
- Registry item: https://txbrendan.dev/r/svg-icon-library.json

## Install

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

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

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

   ```json
   {
     "registries": {
       "@txbrendan": "https://txbrendan.dev/r/{name}.json"
     }
   }
   ```

   Without this step, the shadcn CLI looks up `@txbrendan` in a public list that txbrendan/ui 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 @txbrendan/theme
   ```

3. Add the block. It also adds every component it uses:

   ```bash
   npx shadcn@latest add @txbrendan/svg-icon-library
   ```

## Use it for

- Place one Toaster in your app layout to show brief copy confirmations.
- A downloadable icon collection with names and categories.
- Host trusted SVG files and the optional ZIP on your own origin. Copy needs fetch access; browser downloads work with same-origin URLs.
- Supply your own assets. The block does not install the gallery's example artwork.

## Avoid it for

- A single icon inside a control: use Icon.
- Untrusted uploads. This block does not sanitize or host files.

## Props

- `palette`: `readonly { label: string; value: string }[]`. Editable original hex paints. Overrides apply to SVG paint attributes in previews, copies, downloads, and ZIPs; geometry and transparency stay intact.
- `items`: `readonly SvgIconAsset[]`. Default `[]`. Unique name, visible title, category, and SVG src URL for each icon.
- `downloadAllHref`: `string`. Optional same-origin ZIP for original artwork. With custom colors, a new ZIP of the whole collection is generated locally. Filters never reduce the collection.
- `loading`: `boolean`. Default `false`. Shows placeholders and hides stale artwork and download actions.
- `emptyText`: `string`. Default `"No icons yet."`. Message when the collection has no assets.
- `className`: `string`. Extra classes on the container. Later classes win.

## Accessibility

- Search and category controls have accessible names. Each icon is a named button with aria-pressed selection.
- Copy success uses a toast. Failures, counts, and loading are announced in a status line.
- Copy requires a secure context and clipboard permission. A failed copy keeps the download link available.
- Filtering keeps the preview and download link on a visible result. No matches hides both.

## Examples

### An asset collection

```tsx
<SvgIconLibrary items={[{ name: "ball", title: "Rugby ball", category: "Sport", src: "/icons/ball.svg" }]} downloadAllHref="/icons/collection.zip" />
```