One Prompt to Use IconTree

Prompt

Copy this prompt into your AI tool when you want it to build or integrate IconTree correctly.

# IconTree Integration

Integrate IconTree Lottie icons into an existing app. Do not scaffold a new app, icon library, gallery, marketplace, search page, or design system.

Step 0 — Pick your path

| Project type | Path |
|---|---|
| React (web) | Use the icon-tree-animate npm package — Path A. Skip Path B entirely. |
| Flutter / React Native / Android / other | Use the generic API workflow — Path B. |

Path A — React: icon-tree-animate package

Install

Peer deps: react + react-dom (>=18).

```
npm install icon-tree-animate
```

Add icons (CLI, design-time only)

This searches the IconTree API, saves JSON to `src/icons/<iconId>.json`, and regenerates `src/registry.ts`. Run it once per icon at design time — never at runtime.

```
npx icontree add <iconId> --search "<query>"
npx icontree add heart --search "heart"
npx icontree add arrow-right --search "arrow right" --interactive
# pick from multiple results
```

Use the component

```tsx
import { Icon } from "icon-tree-animate";

<Icon id="heart" size={48} color="#ff0000" mode="static" />
<Icon id="heart" size={48} color="#00ff00" mode="loop" />
<Icon id="heart" size={48} color="#0000ff" mode="onClick" onClick={() => handleClick()} />
<Icon id="heart" size={48} color="#ffaa00" mode="hover" />
```

Props

| Prop | Type | Default | Notes |
|---|---|---|---|
| id | IconId | required | must exist in registry |
| size | number \| string | 24 | width/height |
| color | string | "currentColor" | hex, e.g. "#ff0000" |
| mode | "static"\|"loop"\|"onClick"\|"hover" | "static" | see below |
| onClick | () => void | — | fires in onClick mode |
| resetAfterPlay | boolean | true | reset to frame 0 after playing |
| className | string | — | |
| style | React.CSSProperties | — | |

Modes: `static` = frame 0 only, no animation · `loop` = autoplay, infinite · `onClick` = idle at frame 0, plays once on click · `hover` = idle at frame 0, plays once on mouse-enter, finishes on mouse-leave.

How it works

Design-time (CLI): add-icon.js fetches raw Lottie JSON, saves to `src/icons/`, no color applied.
Runtime (component): icon JSON loaded via dynamic import (tree-shakeable), recolored in-memory from the `color` prop, rendered via Lottie. Zero network requests. `recolorLottie()` deep-clones the JSON, converts hex → Lottie RGBA floats, walks the layer tree updating fill/stroke, and memoizes by icon+color.

Integration rules

Wire `<Icon />` into existing components only; reuse existing spacing/colors/theme/naming.
`color` prop should read from the app's theme tokens (light/dark), not hardcoded hex, unless the project already hardcodes colors elsewhere.
Output only the required code — no README, no extra files, no console logs.
If the user explicitly wants an in-app icon picker/search UI, pause and confirm — that's a different feature from this integration and needs the search API shipped client-side (normally out of scope).

Path B — Non-React (Flutter / React Native / Android / other)

Target (fill in)

Framework: [Flutter / React Native / Android / etc.]
Component: [component name]
Lottie library: [lottie_flutter, lottie-react-native, lottie-android, etc.]
Local icon path: [e.g. assets/icons]

Ground rules

Integrate into existing UI only — no new icon library/gallery/marketplace/search page/design system.
Reuse existing components, spacing, colors, theme, naming.
Output only required code — no README, boilerplate, explanations, unrelated files, console/print logs.
IconTree provides only Lottie .json — never SVG.

Design-time icon selection (AI performs this, not the app)

Base URL: https://icontree.cosmoscope.workers.dev

Search:
```
GET /icon/search?q=<query>&category=<optional>&page=<optional>&pageSize=<optional>
→ { "results": [ { "url": "/path/icon.json" } ] }
```

Workflow: search → pick best match → download (see Theming below) → bundle JSON as a local asset → final code references the local asset only, never the live URL. Never ship search/fetch calls inside the app. If the user wants an in-app picker/search UI, confirm first — separate feature.

Runtime (production)

Import the local JSON, render with the project's existing Lottie library, no network requests, no dynamic fetching.

Theming / icon color

IconTree JSON ships with a fixed baked-in fill (often white/black) that won't match app theme. Two options:

1. Server-side recolor (recommended) — at design time, download the pre-colored variant instead of the raw icon:
   ```
   GET {baseUrl}/icon/use/<iconname>.json?color=<hex>
   e.g. /icon/use/arrow-right-bold.json?color=ff0000
   ```
   Leading # optional (ff0000 or %23ff0000 both work). Bundle the returned JSON directly — no runtime color code needed. For light/dark support, download + bundle one colored JSON per theme (e.g. `icon-name.light.json` / `icon-name.dark.json`) and switch assets on active theme.

2. Runtime recolor — only if the app must recolor dynamically without a rebuild: use the platform Lottie library's native color-override mechanism (dynamic properties, color filters, or JSON preprocessing that swaps fill/stroke). Prefer option 1 otherwise.

Component requirements

Follow existing project architecture/patterns.
Keep size, loop, autoplay, etc. configurable via props/params unless the project already hardcodes equivalents.
Proper typing (TS/Dart/etc. as applicable).
Production-ready code, no TODOs/placeholders/console logs.