@iconly/react

React components and hooks for Iconly icons, Lottie animations, and 3D models.

Install

npm install @iconly/react @tanstack/react-query

Optional peers:

npm install lottie-web   # for IconlyAnimation

Setup

1. Create an API key at Iconly Settings → Developer
2. Wrap your app:

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { IconlyProvider, IconlyIcon } from "@iconly/react";

const queryClient = new QueryClient();

function App() {
  return (
    <QueryClientProvider client={queryClient}>
      <IconlyProvider apiKey={process.env.ICONLY_API_KEY!}>
        <IconlyIcon id={123} size={24} color="currentColor" />
      </IconlyProvider>
    </QueryClientProvider>
  );
}

Subscription

• Free assets — work without a Pro subscription
• Premium assets — require the API key owner to have an active Pro subscription
• Locked assets show a preview image and upgrade link

Check subscription status:

import { useSubscriptionStatus } from "@iconly/react";

function ProBadge() {
  const { data } = useSubscriptionStatus();
  return data?.is_subscribed ? <span>Pro</span> : null;
}

Server-side (Next.js)

import { getIconSvg, getAnimationLottie, get3DModel } from "@iconly/react/server";

const icon = await getIconSvg({ apiKey: process.env.ICONLY_API_KEY!, id: 123 });

API key security

Never expose your API key in client-side bundles for production apps.

| Approach | When to use | |----------|-------------| | Server env + @iconly/react/server | Next.js, Remix, server routes | | apiProxyUrl + backend proxy | Vite, CRA, client SPAs |

Components

IconlyIcon

<IconlyIcon id={123} size={24} color="#333" strokeWidth={1.5} />

IconlyAnimation

<IconlyAnimation id={45} width={120} height={120} loop autoplay />

Iconly3DModel

<Iconly3DModel id={7} width={120} height={120} showDownloadLink />

Hooks

const { data } = useIconlySearch({ resource: "icons", q: "home" });
const { data: icon } = useIconlyAsset("icons", 123);
const { data: profile } = useSubscriptionStatus();

Custom premium fallback

<IconlyIcon
  id={123}
  fallback={<span>Upgrade to access this icon</span>}
  onPremiumRequired={({ name }) => console.log(`Locked: ${name}`)}
/>

License

MIT