React

Icon Forge gives you React components — one .tsx file per icon, with inline SVG and standard prop forwarding. No runtime dependency, no icon font. Just local source files you import like your own code.

Install a pack

From your project root:

npx @icon-forge/cli install acme/brand/core-icons --framework react

The CLI downloads the published pack and writes it into your project:

src/components/icons/core-icons/
├── ArrowLeft.tsx
├── CheckCircle.tsx
├── Home.tsx
├── Settings.tsx
├── ...
└── index.ts

On the first install, the CLI creates two tracking files at the project root:

• iconforge.json — your install config (framework, output directory, which packs you’re tracking)
• iconforge-lock.json — exact record of what’s installed (versions, file hashes)

Commit both, along with the component directory.

Your framework choice is saved after the first install — the CLI won’t ask again.

Importing icons

Each pack gets a barrel index.ts, so named imports work out of the box:

import { ArrowLeft, CheckCircle, Home } from "@/components/icons/core-icons";

Or import individual files directly:

import ArrowLeft from "@/components/icons/core-icons/ArrowLeft";

Using icons in components

Icons behave like any other React component. They render an inline <svg> and forward all standard SVG props to the root element.

import { ArrowLeft, CheckCircle } from "@/components/icons/core-icons";

export function Toolbar() {
  return (
    <div className="flex items-center gap-2">
      <ArrowLeft className="h-5 w-5" />
      <CheckCircle className="h-5 w-5 text-emerald-600" />
    </div>
  );
}

Sizing and color

• Default color is currentColor — icons inherit your text color
• Default size is 1em
• Pass className, style, width, height, or any SVG attribute to customize

The standard Tailwind / utility-class pattern works as you’d expect:

<Home className="h-6 w-6 text-muted-foreground" />

Event handlers

Since props are forwarded to the <svg>, event handlers work directly:

<ArrowLeft className="h-5 w-5 cursor-pointer" onClick={handleBack} />

Refs

Icons forward refs to the underlying <svg> element:

import { useRef } from "react";
import { Home } from "@/components/icons/core-icons";

function Example() {
  const svgRef = useRef<SVGSVGElement>(null);
  return <Home ref={svgRef} className="h-5 w-5" />;
}

Accessibility

Icons are presentational by default. If an icon carries meaning (not just decoration), add a label at the call site:

<CheckCircle aria-label="Success" className="h-5 w-5 text-green-600" />

For decorative icons next to text, no extra attributes are needed — screen readers will skip the SVG.

Wrapping icons

The installed component files are managed by the CLI — they get replaced on the next install or update. If you need app-specific behavior (animation, tooltips, semantic wrappers), build a wrapper component in your own code:

import { CheckCircle } from "@/components/icons/core-icons";
import type { SVGProps } from "react";

interface StatusIconProps extends SVGProps<SVGSVGElement> {
  status: "success" | "error" | "pending";
}

export function StatusIcon({ status, ...props }: StatusIconProps) {
  if (status === "success") return <CheckCircle {...props} />;
  // ...
}

Don’t edit the generated files directly — your changes will be overwritten.

Updating

When the design team publishes a new version of the pack:

npx @icon-forge/cli install acme/brand/core-icons

The CLI pulls the latest release and replaces the tracked files. Component names (based on slot names) stay stable across updates unless the pack author renamed a slot.

To lock to a specific release:

npx @icon-forge/cli install acme/brand/core-icons --version 8f3a9c2d14be

See Updating & Pinning for more on version management.

Multiple packs

You can install multiple packs into the same React project. Each gets its own folder:

src/components/icons/
├── core-icons/
│   ├── Home.tsx
│   └── index.ts
└── nav-icons/
    ├── ChevronLeft.tsx
    └── index.ts

Import from each barrel separately:

import { Home } from "@/components/icons/core-icons";
import { ChevronLeft } from "@/components/icons/nav-icons";

Output customization

Change where packs are written:

# Different base directory
npx @icon-forge/cli install acme/brand/core-icons --output-dir src/icons

# Different folder name for this pack
npx @icon-forge/cli install acme/brand/core-icons --dir-name core

These settings are saved in iconforge.json after the first install.

Next steps

Config & Lockfile

How iconforge.json and iconforge-lock.json work.

Read more →

The Workspace

How icon packs are built on the curate side.

Read more →

Publishing

How releases and namespaces work.

Read more →