Recipes, from a single icon to a searchable picker. They are React with Tailwind classes; the props work the same in every package, and each package page shows its own spelling. Every icon used here is a real name you can import.
import { IconHeart } from "@devigner-ui/icons/Heart";
export function Like() {
return <IconHeart className="size-6" />;
}Import each icon from its own subpath. Your bundle then holds only the icons you use, with no tree shaking to rely on.
Icons paint with currentColor and fill the box you give them, so size and
colour are plain CSS:
<IconHeart className="size-4" />
<IconHeart className="size-6 text-rose-600" />
<IconHeart className="size-10 text-zinc-400 hover:text-rose-600" /><IconHeart />
<IconHeart variant="TwoTone" />
<IconHeart variant="Bold" />
<IconHeart variant="Bulk" />
<IconHeart variant="Broken" />strokeWidth changes Outline, TwoTone and Broken. Bold and Bulk keep their
own weight.
<IconHeart strokeWidth={1} className="size-12" />
<IconHeart strokeWidth={2} className="size-4" />A thinner line suits a large icon, and a heavier one keeps a small icon legible.
The icon stays decorative, because the text already names the action:
import { IconTrash } from "@devigner-ui/icons/Trash";
<button className="inline-flex items-center gap-2">
<IconTrash className="size-4" />
Delete
</button>With no visible text, the label goes on the button:
import { IconClose } from "@devigner-ui/icons/Close";
<button aria-label="Close dialog" className="grid size-8 place-items-center rounded-md">
<IconClose className="size-4" />
</button>Label the button rather than the icon. The name then belongs to the thing people click, and the icon stays out of the accessibility tree.
import { IconArrowRight } from "@devigner-ui/icons/ArrowRight";
<a href="/pricing" className="group inline-flex items-center gap-1">
See pricing
<IconArrowRight className="size-4 transition-transform group-hover:translate-x-0.5" />
</a>import { IconAlertTriangle } from "@devigner-ui/icons/AlertTriangle";
<div role="alert" className="flex gap-3 rounded-lg bg-amber-50 p-4 text-amber-900">
<IconAlertTriangle variant="Bulk" className="size-5 shrink-0" />
<p>Your trial ends in 3 days. Add a card to keep your projects.</p>
</div>Outline for the resting state and Bold for the selected one. The shape stays the same, so only the weight changes:
import { IconHome } from "@devigner-ui/icons/Home";
function NavItem({ active }: { active: boolean }) {
return (
<a aria-current={active ? "page" : undefined} className="flex items-center gap-2">
<IconHome variant={active ? "Bold" : "Outline"} className="size-5" />
Home
</a>
);
}import { useState } from "react";
import { IconStar } from "@devigner-ui/icons/Star";
function Favourite() {
const [on, setOn] = useState(false);
return (
<button aria-pressed={on} aria-label="Favourite" onClick={() => setOn(!on)}>
<IconStar
variant={on ? "Bold" : "Outline"}
className={on ? "size-5 text-amber-500" : "size-5 text-zinc-400"}
/>
</button>
);
}aria-pressed tells assistive technology that the button is on. The icon's
style only shows it.
import { useState } from "react";
import { IconEye } from "@devigner-ui/icons/Eye";
import { IconEyeSlash } from "@devigner-ui/icons/EyeSlash";
function PasswordField() {
const [shown, setShown] = useState(false);
const Icon = shown ? IconEyeSlash : IconEye;
return (
<div className="relative">
<input type={shown ? "text" : "password"} className="w-full pr-10" />
<button
type="button"
aria-label={shown ? "Hide password" : "Show password"}
onClick={() => setShown(!shown)}
className="absolute inset-y-0 right-0 grid w-10 place-items-center"
>
<Icon className="size-4" />
</button>
</div>
);
}import { useState } from "react";
import { IconCopy } from "@devigner-ui/icons/Copy";
import { IconCopySuccess } from "@devigner-ui/icons/CopySuccess";
function CopyButton({ text }: { text: string }) {
const [copied, setCopied] = useState(false);
const copy = async () => {
await navigator.clipboard.writeText(text);
setCopied(true);
setTimeout(() => setCopied(false), 2000);
};
const Icon = copied ? IconCopySuccess : IconCopy;
return (
<button aria-label={copied ? "Copied" : "Copy"} onClick={copy}>
<Icon className="size-4" />
</button>
);
}import { IconLoading } from "@devigner-ui/icons/Loading";
<button disabled className="inline-flex items-center gap-2">
<IconLoading className="size-4 animate-spin motion-reduce:animate-none" />
Saving
</button>import { IconSun } from "@devigner-ui/icons/Sun";
import { IconMoon } from "@devigner-ui/icons/Moon";
function ThemeToggle({ dark, onToggle }: { dark: boolean; onToggle: () => void }) {
return (
<button aria-label={dark ? "Use light theme" : "Use dark theme"} onClick={onToggle}>
{dark ? <IconSun className="size-5" /> : <IconMoon className="size-5" />}
</button>
);
}import { IconBell } from "@devigner-ui/icons/Bell";
function Notifications({ count }: { count: number }) {
return (
<button aria-label={`Notifications, ${count} unread`} className="relative">
<IconBell className="size-6" />
{count > 0 && (
<span className="absolute -right-1 -top-1 min-w-4 rounded-full bg-rose-600 px-1 text-[10px] text-white">
{count > 99 ? "99+" : count}
</span>
)}
</button>
);
}The count is part of the button's label, so a screen reader hears it once.
import { IconMagnifier } from "@devigner-ui/icons/Magnifier";
<label className="relative block">
<span className="sr-only">Search</span>
<IconMagnifier className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-zinc-400" />
<input type="search" placeholder="Search icons" className="w-full pl-9" />
</label>pointer-events-none lets a click on the icon reach the input under it.
import { IconStar } from "@devigner-ui/icons/Star";
function Rating({ value }: { value: number }) {
return (
<div role="img" aria-label={`${value} out of 5`} className="flex text-amber-500">
{[1, 2, 3, 4, 5].map((n) => (
<IconStar key={n} variant={n <= value ? "Bold" : "Outline"} className="size-4" />
))}
</div>
);
}Pass the style down once, rather than repeating variant on every icon:
import { createContext, useContext } from "react";
import type { IconComponentType, IconProps, IconVariant } from "@devigner-ui/icons";
const IconStyle = createContext<IconVariant>("Outline");
export function Icon({ as: Component, ...props }: IconProps & { as: IconComponentType }) {
const variant = useContext(IconStyle);
return <Component variant={variant} {...props} />;
}
// Anywhere below this, <Icon as={IconHeart} /> draws TwoTone.
<IconStyle.Provider value="TwoTone">
<App />
</IconStyle.Provider>A variant prop on one icon still wins, because it comes after the context
value.
Write the names you need as a map. It keeps strings type-safe, and it keeps the bundle small:
import { IconHome } from "@devigner-ui/icons/Home";
import { IconSettings } from "@devigner-ui/icons/Settings";
import { IconUser } from "@devigner-ui/icons/User";
import type { IconComponentType } from "@devigner-ui/icons";
const NAV = {
home: IconHome,
account: IconUser,
settings: IconSettings,
} satisfies Record<string, IconComponentType>;
function NavIcon({ name }: { name: keyof typeof NAV }) {
const Icon = NAV[name];
return <Icon className="size-5" />;
}When a name arrives as data, load each icon only when it is needed. Bundlers cannot follow a template string into a package, so list the loaders:
import { lazy, Suspense } from "react";
const LOADERS = {
Heart: () => import("@devigner-ui/icons/Heart"),
Star: () => import("@devigner-ui/icons/Star"),
Bell: () => import("@devigner-ui/icons/Bell"),
};
const LAZY = Object.fromEntries(
Object.entries(LOADERS).map(([name, load]) => [name, lazy(load)]),
) as Record<keyof typeof LOADERS, React.ComponentType<{ className?: string }>>;
function CmsIcon({ name }: { name: string }) {
const Icon = LAZY[name as keyof typeof LOADERS];
if (!Icon) return null;
return (
<Suspense fallback={<span className="inline-block size-6" />}>
<Icon className="size-6" />
</Suspense>
);
}lazy works here because every subpath has the component as its default
export. The fallback keeps the icon's space, so the layout does not move when
it loads.
For an admin tool or an icon picker, where any of the 2,496 icons can come up, import the namespace. Nothing tree shakes, so keep this out of pages that visitors load first.
import * as Icons from "@devigner-ui/icons";
import type { IconComponentType, IconName } from "@devigner-ui/icons";
function isIconName(name: string): name is IconName {
return `Icon${name}` in Icons;
}
function AnyIcon({ name }: { name: string }) {
if (!isIconName(name)) return null;
const Icon = Icons[`Icon${name}`] as IconComponentType;
return <Icon className="size-6" />;
}Every icon forwards its ref to the <svg>, so it can be a trigger itself:
import * as Tooltip from "@radix-ui/react-tooltip";
import { IconInfoCircle } from "@devigner-ui/icons/InfoCircle";
<Tooltip.Root>
<Tooltip.Trigger asChild>
<IconInfoCircle tabIndex={0} aria-label="About billing" className="size-4" />
</Tooltip.Trigger>
<Tooltip.Content>Charged on the first of each month.</Tooltip.Content>
</Tooltip.Root>tabIndex={0} lets keyboard users reach the icon, and the label turns it into
an image with a name.
For apps that size icons in CSS rather than with classes, the optional
stylesheet adds an .icon class driven by three variables:
import "@devigner-ui/icons/styles.css";
<nav style={{ "--icon-size": "20px", "--icon-stroke-width": 2 } as React.CSSProperties}>
<IconHome className="icon" />
<IconUser className="icon" />
</nav>CSS stroke-width wins over the attribute, so --icon-stroke-width overrides
strokeWidth.
metadata.json lists every icon with its category, keywords and old names:
import metadata from "@devigner-ui/icons/metadata.json";
const heart = metadata.icons.find((i) => i.name === "Heart");
heart?.category; // its category slug
heart?.keywords; // the words it is found by
heart?.formerly; // names it had before 3.5.0Search names and keywords together, then render the matches through the namespace:
import { useMemo, useState } from "react";
import * as Icons from "@devigner-ui/icons";
import metadata from "@devigner-ui/icons/metadata.json";
import type { IconComponentType } from "@devigner-ui/icons";
function IconPicker({ onPick }: { onPick: (name: string) => void }) {
const [query, setQuery] = useState("");
const matches = useMemo(() => {
const q = query.trim().toLowerCase();
if (!q) return metadata.icons.slice(0, 60);
return metadata.icons
.filter(
(icon) =>
icon.name.toLowerCase().includes(q) ||
icon.keywords.some((k) => k.includes(q)),
)
.slice(0, 60);
}, [query]);
return (
<div>
<input
type="search"
aria-label="Search icons"
value={query}
onChange={(e) => setQuery(e.target.value)}
/>
<ul className="grid grid-cols-8 gap-1">
{matches.map(({ name }) => {
const Icon = Icons[`Icon${name}` as keyof typeof Icons] as IconComponentType;
return (
<li key={name}>
<button aria-label={name} onClick={() => onPick(name)} className="grid size-10 place-items-center">
<Icon className="size-5" />
</button>
</li>
);
})}
</ul>
</div>
);
}Showing 60 at a time keeps the list fast while someone types.
embeddings.json holds a vector for every icon, so "checkout" can find a cart
even though the word is not in its name. The API reference
has the full function, and AI search explains how it
ranks.
If a database stores icon names from before 3.5.0, map them forward on read:
import renames from "@devigner-ui/icons/renames.json";
const current: Record<string, string> = Object.fromEntries(
renames.batches.flatMap((batch) => Object.entries(batch.renames)),
);
const name = current[saved] ?? saved; // "Bag2" becomes "BagStraps"<img> from a CDN<img
src="https://cdn.jsdelivr.net/npm/@devigner-ui/icons-svg@3.5.0/svg/outline/Heart.svg"
alt=""
width="24"
height="24"
/>An <img> cannot take the page's colour. Inline the SVG when it has to match
the text.
<svg width="24" height="24" aria-hidden="true">
<use href="/sprite/bold.svg#Heart" />
</svg>Serve the sprite from your own site: browsers block <use> across origins.
The SVG page covers the setup and the trade-offs.
Icons are hidden from the accessibility tree until they have a label, so a test finds a control by its label, not by its glyph:
import { render, screen } from "@testing-library/react";
render(<Notifications count={3} />);
screen.getByRole("button", { name: "Notifications, 3 unread" });
render(<IconInfoCircle aria-label="About billing" />);
screen.getByRole("img", { name: "About billing" });