DocyrusIcon

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

Edit on GitHubEditllms.txt

iOSAndroid

Preview DocyrusIcon on your device

Scan with Expo Go

iOS Android

Download Expo Go, then scan the QR code to preview native components.

Installation

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

Required Packages(2 packages)

pnpm add react-native-svg react-native-reanimated

Usage

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

<DocyrusIcon icon="fal star" size="lg" />
<DocyrusIcon icon="huge notification-01" color="primary" />
<DocyrusIcon icon="fas heart" size={32} color="destructive" />
<DocyrusIcon icon="fal user" color="indigo-500" />
<DocyrusIcon icon="dot" color="success" />

Animations

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

<DocyrusIcon icon="fal spinner" animation="spin" />
<DocyrusIcon icon="fal bell" animation="pulse" />
<DocyrusIcon icon="fal arrow-down" animation="bounce" />
<DocyrusIcon icon="fas circle" animation="ping" color="success" />

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

<DocyrusIcon icon="fal trash" color="destructive" onPress={handleDelete} />

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`

DocyrusIcon

On this page