Quick start

Any icon from the Iconavo catalog by its name, with one HTML tag or one React component. Only the icons on the page are loaded, in batches, and if a host fails, they come from the next one.

Beta. Versions 0.x are published under the next tag. The API may still change before 1.0.

Icon names are set:icon, for example lucide:house. Both parts use lowercase Latin letters, digits and single hyphens. The sets are Lucide (lucide), Tabler Icons (tabler), Material Symbols (material-symbols), Phosphor (ph) and Fluent Emoji Flat (fluent-emoji-flat), with the same names and prefixes as on Iconify.

Install

Without a build step, add two lines to <head>:

<script type="module" src="https://cdn.jsdelivr.net/npm/@iconavo-ui/icon@0.1.0/dist/iconavo-icon.js"></script>
<style>iconavo-icon:not(:defined) { display: inline-block; width: 1em; height: 1em; }</style>

The script is a single ES module with everything inside. The style keeps a 1em square for each icon until the script has run, so the text next to icons does not jump; it does not know about the width and height attributes.

With npm:

npm install @iconavo-ui/icon@next

import "@iconavo-ui/icon"; // registers <iconavo-icon>

For React:

npm install @iconavo-ui/react@next

With pnpm or yarn: pnpm add @iconavo-ui/react@next, yarn add @iconavo-ui/react@next. Until 1.0, new versions are published under the next tag, so install with @next.

Examples

HTML

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <script type="module" src="https://cdn.jsdelivr.net/npm/@iconavo-ui/icon@0.1.0/dist/iconavo-icon.js"></script>
    <style>iconavo-icon:not(:defined) { display: inline-block; width: 1em; height: 1em; }</style>
  </head>
  <body>
    <a href="/"><iconavo-icon icon="lucide:house"></iconavo-icon> Home</a>
  </body>
</html>

React

import { Icon } from "@iconavo-ui/react";

export function HomeLink() {
  return (
    <a href="/">
      <Icon icon="lucide:house" /> Home
    </a>
  );
}

Size and color

An icon is as tall as the text (1em) and takes the text color, so CSS sizes and colors it like text:

<h2 style="font-size: 32px; color: crimson">
  <iconavo-icon icon="lucide:heart"></iconavo-icon> Favorites
</h2>

Or set them on the icon:

<iconavo-icon icon="lucide:heart" width="32" color="crimson" stroke-width="1.5"></iconavo-icon>

<Icon icon="lucide:heart" width={32} color="crimson" strokeWidth={1.5} />

With only width or only height, the other side follows the icon's proportions. stroke-width changes the lines of line icons, such as Lucide and the outline icons of Tabler; other icons ignore it.

A label for screen readers

Icons are decorative by default, and screen readers skip them. An icon that is the only content of a button needs a label:

<button type="button">
  <iconavo-icon icon="lucide:trash" label="Delete"></iconavo-icon>
</button>

<button type="button">
  <iconavo-icon icon="lucide:trash"></iconavo-icon> Delete
</button>

A screen reader announces both buttons as "Delete". In the first one, the name comes from the label; in the second, from the text, and the icon is skipped. The label is not shown as a tooltip.

Your own host

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

configure({
  api: ["https://icons.example.com/api"],
  cdn: ["https://icons.example.com/static"],
});

Each list replaces ours, so icons now load only from icons.example.com. To keep our hosts as a fallback, add them to the lists yourself. Call configure() before the first icon renders, in the same module that imports the package. See also What your own host must serve.

Without a build step, import configure from the same address as the script, in a single module:

<script type="module">
  import { configure } from "https://cdn.jsdelivr.net/npm/@iconavo-ui/icon@0.1.0/dist/iconavo-icon.js";
  configure({ api: ["https://icons.example.com/api"], cdn: ["https://icons.example.com/static"] });
</script>

Live examples

Open an example in the browser, change the code, and the preview updates:

The examples run on StackBlitz.

The Next.js example shows icons in the server HTML with IconavoProvider, and icons loaded in the browser. StackBlitz can't run Next.js 16 yet, so create a project from it on your computer:

npx create-next-app@latest --example https://github.com/iconavo/iconavo/tree/main/examples/starters/next my-icons

The code of all examples is in examples/starters.

Edit this page on GitHub