Recipes

Without network requests

Save the icons you use to a file, add them with addIcons, and turn the hosts off:

curl -o src/icons/lucide.json "https://api.iconavo.dev/lucide.json?icons=heart,house,search"

import { addIcons, configure } from "@iconavo-ui/icon";
import lucide from "./icons/lucide.json";

addIcons(lucide);
configure({ api: [], cdn: [] });

Icons in your bundle also stay the same when the sets update. Whole sets come in the npm packages @iconavo-ui/icons-{set}, but they are large: from about 0.1 MB (Lucide) to 1.5 MB (Material Symbols) gzipped.

Next.js and server rendering

// app/layout.tsx is a Server Component
import { IconavoProvider, loadIcons } from "@iconavo-ui/react";

export default async function RootLayout({ children }: { children: React.ReactNode }) {
  const icons = await loadIcons(["lucide:house", "lucide:search"]);
  return (
    <html lang="en">
      <body>
        <IconavoProvider icons={icons}>{children}</IconavoProvider>
      </body>
    </html>
  );
}

// any Server or Client Component inside
import { Icon } from "@iconavo-ui/react";

<Icon icon="lucide:house" />;

• Icons passed to IconavoProvider are in the server HTML, so there is no flash.
• Other icons render the placeholder on the server and load in the browser after hydration. The server and the browser draw the same markup, so there are no hydration warnings.
• Icons added with addIcons at the top level of a module appear right after hydration. Do not call addIcons during rendering: on the server, memory is shared by all requests.
• Next.js builds Server Components and Client Components separately, and each build has its own copy of the icon store. Call configure, setLoader and top-level addIcons in a module that both your layout and a Client Component import: the layout's copy serves loadIcons on the server, the other one serves the browser.

loadIcons on the server

• loadIcons waits for the hosts, at most 5 seconds, so a page rendered on request sends its first byte only after the icons arrive.
• Loaded icons stay in the server's memory: later calls return them without a request.
• In the Next.js App Router, a layout that reads no request data, such as cookies or headers, is rendered at build time, so its icons load once, during the build.
• On pages rendered on request, pass to IconavoProvider only the icons above the fold; the others load in the browser.

What your own host must serve

• api: GET {host}/{set}.json?icons=a,b returns IconifyJSON with the requested icons, the alias chains of the requested aliases, and the missing names in not_found. An unknown set is a 404.
• cdn: GET {host}/manifest.json returns {"sets": {"lucide": {"version": "…"}}}, and GET {host}/v/{version}/{set}/{icon}.json returns IconifyJSON with one icon.
• Both answer plain GET requests with Access-Control-Allow-Origin that allows your site. The core sends no custom headers, so there are no preflight requests.

The simplest host is a caching reverse proxy to api.iconavo.dev and cdn.iconavo.dev. A self-hosted Iconify API answers batches too.

The full reference of our API, with the SVG and CSS addresses, is in the edge API documentation.

Edit this page on GitHub