Mastericons
Sign in
@mastericons/react

200K+ icons in React.
Zero bundle weight.

CDN-backed React components for Mastericons. Fetch optimized SVGs on demand — no need to install every icon pack.

Get startedView APInpm

Overview

A lightweight runtime layer over the Mastericons CDN — built for modern React apps.

No bundle bloat

Icons load from the Mastericons CDN at runtime. Your app ships a tiny package — not 200K+ SVG files.

200K+ icons

Lucide, Tabler, Phosphor, Heroicons, and 50+ more libraries — one consistent API.

On-demand fetch

Only icons you render are fetched. In-flight requests are deduplicated and cached in memory.

Domain-locked keys

Publishable API keys are safe in the browser. Each key is restricted to origins you configure in your account.

Styled output

Set size, color, and stroke width as props. The package applies styles to the fetched SVG for you.

Accessible by default

Pass title or aria-label for screen readers. Icons are decorative when neither is provided.

Installation

Install the package and ensure React 18+ is available.

terminal
npm install @mastericons/react

Peer dependencies: react and react-dom>= 18.

Quick start

Wrap your app once with your API key, then render icons by ID.

App.tsx
// .env  →  NEXT_PUBLIC_MASTERICONS_API_KEY=mi_pub_...
import { Icon, MastericonsProvider } from "@mastericons/react";

export function App() {
  return (
    // Key is read from the env var automatically — set once, never repeated.
    <MastericonsProvider>
      <Icon icon="lucide:home" size={24} color="currentColor" />
    </MastericonsProvider>
  );
}

API keys

Pro and Lifetime subscribers can create publishable, domain-locked API keys for the React library.

Keys are safe to use in the browser. Each key is restricted to the origins you configure — requests from other domains are rejected.

Create API key

Set the key once — you never repeat it on individual icons. Pick whichever fits your setup:

  • Set NEXT_PUBLIC_MASTERICONS_API_KEY — the provider reads it automatically (recommended for Next.js).
  • Call configureMastericons({ apiKey }) once at your entry point (recommended for Vite / non-React).
  • Pass apiKey directly to MastericonsProvider (overrides the others).
main.tsx
// main.tsx (Vite, or any non-React entry)
import { configureMastericons } from "@mastericons/core";

configureMastericons({ apiKey: import.meta.env.VITE_MASTERICONS_API_KEY });

Icon IDs

Reference icons by library and slug. Browse the full catalogue on Mastericons.

PropTypeDefaultDescription
Colon (Iconify-style)string—Example: lucide:home
Hyphen (Mastericons id)string—Example: lucide-home

Next.js & SSR

Icon and MastericonsProvider are client components. Add the provider in a client boundary at your app root.

app/providers.tsx
// app/providers.tsx
"use client";

import { MastericonsProvider } from "@mastericons/react";

export function Providers({ children }: { children: React.ReactNode }) {
  // Reads NEXT_PUBLIC_MASTERICONS_API_KEY automatically.
  return <MastericonsProvider>{children}</MastericonsProvider>;
}

Fetches use the authenticated API at /api/v1/icons/rawwith your API key. In the browser, the Origin header is validated against your key's allowlist.

API reference

Exports from @mastericons/react.

MastericonsProvider

Supplies API key and fetch configuration to all icons in the subtree. Wrap your app or any section that renders icons.

Provider.tsx
<MastericonsProvider
  apiKey="mi_pub_..."
  corsApiBase="https://mastericons.com"
  fetch={customFetch}
>
  {children}
</MastericonsProvider>
PropTypeDefaultDescription
apiKeystringenv / configure()Publishable API key. Optional if set via NEXT_PUBLIC_MASTERICONS_API_KEY or configureMastericons().
corsApiBasestringhttps://mastericons.comSite origin for the authenticated API (/api/v1/icons/raw).
cdnBasestringhttps://icons.mastericons.comCDN origin (legacy; unused when apiKey is set).
catalogVersionstringbaked at publishCache-bust query param on direct CDN URLs (?v=).
directCdnbooleanfalseIgnored when apiKey is set.
fetchtypeof fetchglobalThis.fetchCustom fetch implementation (SSR, tests, or middleware).
childrenReactNode—App content that renders icons.

Icon

Renders a single icon by ID. Shows fallback while loading or when fetch fails.

Icon.tsx
<Icon
  icon="lucide:home"
  size={24}
  color="currentColor"
  strokeWidth={1.5}
  title="Home"
  aria-label="Home"
  fallback={<span aria-hidden>…</span>}
/>
PropTypeDefaultDescription
iconstring—Icon identifier (required).
sizenumber | string24Width and height applied to the SVG.
colorstringcurrentColorReplaces currentColor in the fetched SVG.
strokeWidthnumber—Override stroke width on the SVG.
titlestring—Accessible title element inside the SVG.
fallbackReactNodenullContent shown while loading or on error.
aria-labelstring—Accessible name when the icon conveys meaning.
aria-hiddenbooleantrue*Defaults to true when neither title nor aria-label is set.

useIconSvg

Lower-level hook when you need the styled SVG string instead of the Icon component.

CustomIcon.tsx
import { useIconSvg } from "@mastericons/react";

function CustomIcon() {
  const { svg, loading, error } = useIconSvg({
    icon: "lucide:home",
    size: 32,
    color: "#DF0E5D",
  });

  if (loading || error || !svg) return null;
  return <span dangerouslySetInnerHTML={{ __html: svg }} />;
}
PropTypeDefaultDescription
iconstring—Icon identifier (required).
sizenumber | string—Width and height for the SVG.
colorstring—Color applied to the SVG.
strokeWidthnumber—Stroke width override.
classNamestring—Class applied to the root SVG element.
titlestring—Accessible title inside the SVG.
ariaLabelstring—Accessible label for the SVG.
ariaHiddenboolean—Whether the SVG is hidden from assistive tech.

Returns { svg, loading, error }. Also exports useMastericonsConfig() to read the active provider config.

Licensing

@mastericons/react is MIT-licensed and ships code only — no SVG assets are bundled. Icons are loaded from the Mastericons CDN and originate from many upstream libraries with their own licenses. See the monorepo NOTICE for attribution details.

Best practices

Tips for production React apps.

Wrap once with MastericonsProvider

Place the provider at your app root with your publishable API key. All Icon and useIconSvg calls share the same config and fetch implementation.

Add your origins when creating a key

Include every domain where your app runs — e.g. http://localhost:3000 for local dev and https://myapp.com for production. Requests from unlisted origins are rejected.

Use colon or hyphen IDs

Both lucide:home and lucide-home work. Copy IDs from the browse page or use the library:slug format familiar from Iconify.

Provide a fallback for loading states

The Icon component shows fallback while fetching or on error. Use a skeleton or placeholder to avoid layout shift in lists and nav bars.

Prefer title or aria-label for meaning

Icons without a title or aria-label are marked aria-hidden. Add one when the icon conveys information, not just decoration.

Use @mastericons/core for custom UIs

Need fetchIconSvg or URL builders outside React? Import from @mastericons/core — the React package wraps the same primitives.

Ready to ship icons
without the bundle?

npm install @mastericons/react — then pick any icon from 200K+.

Get startedBrowse iconsGitHub