# rn-docyrus-icon
URL: /docs/native/docyrus/docyrus-icon

CDN-powered icon component supporting Font Awesome, Huge Icons, emojis and custom libraries, with an SVG cache, a same-footprint loader and looping animations.

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/rn-docyrus-icon
```

**Dependencies:**
- [react-native-svg](https://www.npmjs.com/package/react-native-svg)
- [react-native-reanimated](https://www.npmjs.com/package/react-native-reanimated)

## Usage

```tsx
import { DocyrusIcon } from '@/components/docyrus-native/docyrus-icon';

```

### Animations

Same names as the web `animation` variant (`animate-*`), driven by `react-native-reanimated` loops.

```tsx

```

| Animation | Effect | Cycle |
|-----------|--------|-------|
| `'none'` | No animation | — |
| `'spin'` | 360° rotation, linear | 1 s |
| `'pulse'` | Opacity 1 → 0.5 → 1 | 2 s |
| `'bounce'` | Vertical bounce (25% of the icon size) | 1 s |
| `'ping'` | Scale 1 → 2 while fading out | 1 s |

### Pressable

```tsx

```

## Loading & caching

- **SVG cache** — every SVG is fetched once per app session. A module-level cache keyed by URL stores resolved markup (read synchronously, so a remount or a list row scrolled back into view renders instantly) and shares in-flight requests, so 100 rows showing the same icon trigger ONE network request. Failed requests are dropped from the cache so a later mount retries.
- **Same-footprint placeholder** — while an SVG loads (or when it fails), a `size × size` rounded square at 10% opacity in the icon colour is rendered, exactly like web, so layouts never shift when the icon arrives.

## Colour

`color` accepts:

| Value | Resolves to |
|-------|-------------|
| `'default'` | `colors.foreground` |
| `'muted'` | `colors.mutedForeground` |
| `'primary'` · `'secondary'` · `'accent'` · `'destructive'` · `'success'` · `'warning'` · `'info'` | The matching `DocyThemeProvider` colour |
| Tailwind colour name (`'indigo-500'`, `'blue-200'`) | Hex from the Tailwind palette (`resolveColorHex`, then the theme's full shade palette) |
| Raw colour (`'#f97316'`, `'rgb(…)'`, `'hsl(…)'`, named) | Used as-is |

Theme keys resolve only inside a `DocyThemeProvider`; without one the icon keeps the SVG's own colour (`currentColor` → black). On native, `className="text-*"` does **not** tint the icon (web tints via `currentColor`) — use `color`.

## API Reference

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `icon` | `string` | — | Icon string (e.g. `"fal star"`, `"huge notification-01"`, `"dot"`, or an emoji) |
| `lib` | `string` | `'kv'` | Default icon library when the icon string has no library prefix |
| `group` | `string \| null` | `null` | Icon group/subfolder override |
| `size` | `number \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` | `'default'` | Pixel number, or preset (`xs` 12 · `sm` 16 · `default` 20 · `lg` 24 · `xl` 32) |
| `animation` | `'none' \| 'spin' \| 'pulse' \| 'bounce' \| 'ping'` | `'none'` | Looping animation (web `animation` variant parity) |
| `color` | `DocyrusIconColor` | `'default'` | Theme key, Tailwind colour name or raw colour string |
| `className` | `string` | — | Additional classes for the container |
| `onPress` | `() => void` | — | Press handler — wraps the icon in a `Pressable` |
| `disabled` | `boolean` | `false` | Disabled state (only with `onPress`; renders a plain view) |

### Icon String Format

| Format | Example | Description |
|--------|---------|-------------|
| `"<lib> <name>"` | `"fal star"` | Font Awesome Light star |
| `"<lib> <group> <name>"` | `"huge editor bold"` | Huge Icons with group |
| `"<name>"` | `"settings"` | Uses default lib (`kv`) |
| `"dot"` | `"dot"` | Renders a bullet character |
| `"null"` | `"null"` | Renders `fas square` |
| emoji | `"⭐"` | Renders the emoji directly |

## Exports

| Export | Description |
|--------|-------------|
| `DocyrusIcon` | The icon component (memoized) |
| `parseIcon(icon, defaultLib?)` | Parses an icon string into `ParsedIcon` (native-only helper) |
| `buildIconUrl(lib, group, name)` | Builds the CDN SVG URL (native-only helper) |
| `CDN_BASE` | `https://static.docyrus.app/assets/icons` |

## Type Exports

| Type | Description |
|------|-------------|
| `DocyrusIconProps` | Props for the DocyrusIcon component |
| `DocyrusIconPropsType` | Alias of `DocyrusIconProps` (web parity) |
| `DocyrusIconSize` | `number \| 'xs' \| 'sm' \| 'default' \| 'lg' \| 'xl'` |
| `DocyrusIconAnimation` | `'none' \| 'spin' \| 'pulse' \| 'bounce' \| 'ping'` |
| `DocyrusIconColor` | Theme colour key, Tailwind colour name or raw colour string |
| `ParsedIcon` | `{ lib, group, name, isEmoji, isDot }` returned by `parseIcon` |