Reference

Attributes and props

• Multicolor icons (Fluent Emoji Flat) keep their colors: color and stroke-width do not change them.
• Rotation and flip are drawn inside the SVG, not with a CSS transform, so the icon's box follows the drawing: at 90° and 270° a non-square icon swaps its width and height. Flip is applied before rotation.
• inline lowers the icon by 0.125em, so it sits on the text baseline like a letter.
• Invalid values are ignored: the icon renders without that setting, and the console shows one warning with the allowed values.
• In React, sizes also take numbers (width={32}), and rotate also takes the numbers 1–3. The component always renders an <svg>, also while the icon loads, and other props such as className, style, event handlers and ref go to it.
• Color in React is an attribute of the <svg>, so CSS that targets the <svg> itself, such as a text-* class in className, takes precedence over it.
• With Tailwind CSS, its base styles make every <svg> a block, so an Icon sits on a line of its own. Add className="inline-block" to the icon, or svg { display: inline-block; } to your base styles. The <iconavo-icon> tag is not affected.

Functions

@iconavo-ui/icon and @iconavo-ui/react export the same four functions and share one store of icons and settings for the whole page. Both also export the TypeScript types IconavoIconSet, IconavoIcon and IconavoAlias, the same as in the data packages.

configure(options)

function configure(options: {
  api?: string[];
  cdn?: string[];
  placeholder?: "skeleton" | "spinner" | "none";
  dev?: boolean;
}): void;

• A list replaces the default one, and [] turns that kind of host off.
• Options you leave out keep their values.
• A change applies to requests made after the call, so call configure() before the first icon renders.

addIcons(data)

function addIcons(data: IconavoIconSet | IconavoIconSet[]): void;

Adds icons in IconifyJSON format, one icon set per object. Added icons are never requested from the network. They replace icons with the same names, and icons already on the page redraw. It accepts:

• a batch from our API saved to a file, for example https://api.iconavo.dev/lucide.json?icons=house,heart;
• icons from the data packages @iconavo-ui/icons-{set}, which hold whole sets;
• IconifyJSON from Iconify's @iconify-json/* packages;
• your own icons under your own prefix.

import { addIcons } from "@iconavo-ui/icon";

addIcons({
  prefix: "acme",
  width: 24,
  height: 24,
  icons: {
    logo: { body: '<path fill="currentColor" d="M3 3h18v18H3z"/>' },
  },
});

<iconavo-icon icon="acme:logo"></iconavo-icon>

A prefix follows the same rules as icon names; an invalid one throws an error. Names listed in not_found are remembered as missing.

loadIcons(names)

function loadIcons(names: string[]): Promise<IconavoIconSet[]>;

Loads icons ahead of time: before a menu opens, or on the server for server rendering. It resolves with one IconifyJSON object per set, holding the loaded icons and, in not_found, the missing names.

It never rejects. It makes one pass over the hosts, at most 5 seconds, and leaves out icons that failed to load; components in the browser retry them later. An invalid name goes to not_found with a warning.

setLoader(prefix, loader)

function setLoader(
  prefix: string,
  loader: ((names: string[]) => Promise<IconavoIconSet | null>) | null,
): void;

Loads one set from your own source instead of the hosts: a server with another format, a database, generated icons. It works for our sets too.

• The core calls loader with the names it needs, in batches and without duplicates.
• The result is added as with addIcons. Names missing from it, or a null result, count as missing icons.
• A rejected promise, or one that does not settle within 5 seconds, counts as a failed host and is retried.
• null instead of a function removes the loader.

import { setLoader } from "@iconavo-ui/icon";

setLoader("acme", async (names) => {
  const response = await fetch(`/icons/acme.json?icons=${names.join(",")}`);
  if (!response.ok) throw new Error(`Icons: HTTP ${response.status}`);
  return response.json();
});

IconavoProvider (React)

<IconavoProvider icons={icons}>{children}</IconavoProvider>

Passes icons loaded on the server (IconavoIconSet[], as returned by loadIcons) to the components inside, for the server HTML and for hydration. See Next.js and server rendering.

Loading and errors

While an icon loads

• The icon keeps a 1em × 1em square, or the size you set, so the text around it does not jump. With only one side set, the square has that side; with auto, it is 1em until the icon's own size is known.
• If loading takes longer than 150 ms, a placeholder appears: a skeleton by default, a spinner with placeholder="spinner", nothing with placeholder="none". When the system asks to reduce motion, placeholders do not animate.
• The tag loads an icon when it comes within half a screen of the visible part of the page, so it is usually ready when you scroll to it; noobserver turns this off. The React component loads it when it mounts.
• Inside a scrolling container, and in an iframe from another site, such as a live example's preview, the half-screen margin does not apply: the tag loads an icon when it becomes visible.
• A tag that has never come near the visible part of the page prints empty. Add noobserver to icons that must print.
• In React, placeholders, inline and the development frame come from a stylesheet that the package adds when the page's scripts run. Until then, server-rendered HTML keeps an empty box of the icon's size, and inline icons sit on the baseline.

Batches and hosts

• Icons requested at the same moment (in one tick of the event loop) go out together: one request per set, with sorted names, split into several requests when the address would be longer than 500 characters or hold more than 100 names. For example, 100 Lucide icons take 4 requests. An icon that is already loading is not requested again.
• The hosts are tried in order: api.iconavo.dev sends batches, then cdn.iconavo.dev, cdn2.iconavo.dev and iconavo.b-cdn.net send one icon per request, using their manifest.json to find the current version of a set.
• If api.iconavo.dev does not answer within 1.5 seconds, the same icons are also requested from the static hosts. Static hosts send one icon per request, so the core waits longer before switching to them. Between hosts of the same kind (API hosts or static hosts), the wait is 750 ms. A host that fails outright is not waited for. The first answer wins. After 5 seconds without an answer, the attempt has failed.
• A failed attempt is repeated after 1, 2 and 4 seconds while the icon is on the page, and the placeholder stays meanwhile. After the last attempt, the icon looks like a missing one and the console shows one warning with the error, but the icon is requested again the next time it appears.

Missing icons

• If a set has no such icon, its place stays empty, and the console shows one warning per name.
• A missing name is remembered and not requested again while the page is open.
• In development mode, a dashed frame marks the place. Development mode is on in the development build of your bundler (for example Vite or webpack) and, without a bundler, on pages opened from localhost, 127.0.0.1, [::1] or a file: address. configure({ dev: true }) or configure({ dev: false }) overrides it.
• Names never break: renamed icons still answer to their old names, and icons that their authors removed still render.

Edit this page on GitHub