🖼️ Iconify Downloader

A simple utility to download icons from the Iconify API and save them either as individual SVG files or a JSON collection compatible with Iconify.

✨ Features

• Download any Iconify icon by name (e.g., logos:java)
• Output formats:
  • Individual .svg files
  • Combined .json collection
• Easily configurable with output directory and format
• TypeScript native with typed options
• Optional CLI support

📦 Installation

npm install iconify-downloader

🔧 Usage

import downloadIcons from "iconify-downloader";
const icons = ["logos:java", "fluent:mail-24-filled", "mdi:github"];

await downloadIcons(icons, {
  outputDir: "./icons",
  format: "svg",
});

await downloadIcons(icons);

await downloadIcons(icons, {
  format: "json",
});

await saveAsSVGs(icons, "./icons");

await saveAsJSON(, "./collections");

⚙️ API

downloadIcons(icons: string[], options?: DownloadOptions): Promise<void>

Downloads a list of Iconify icons to the specified directory in specified format.

Parameters

| Name | Type | Default | Description | | -------------- | ----------------- | ------------ | -------------------------------- | | icons | string[] | required | Icon names like ["logos:java"] | | options | DownloadOptions | {} | Optional config | | ├─ outputDir | string | "./icons" | Output directory | | └─ format | "svg" \| "json" | "svg" | Output format |

saveAsSVGs(icons: string[], outputDir: string): Promise<void>

• Downloads a list of Iconify icons and saves each icon as an individual .svg file to the specified directory.
• The output directory will be created automatically if it doesn't exist.

Parameters

| Name | Type | Default | Description | | ----------- | ---------- | ------------ | -------------------------------- | | icons | string[] | required | Icon names like ["logos:java"] | | outputDir | string[] | ./icons | Directory to save the SVG files. |

Output

• Each icon is saved as a separate file like logos-java.svg inside the target directory.
• The output directory will be created automatically if it doesn't exist.

saveAsJSON(icons: string[], outputDir: string): Promise<void>

• Downloads a list of Iconify icons from single set and saves icon set as icon-set.json file to the specified directory which can be added to collection of iconify icons.
• The output directory will be created automatically if it doesn't exist.

Parameters

| Name | Type | Default | Description | | ----------- | ---------- | --------------- | -------------------------------- | | icons | string[] | required | Icon names like ["logos:java"] | | outputDir | string[] | ./collections | Directory to save Icons sets. |

Usage with @iconify/react

import { addCollection } from "@iconify/react";
import icons from "./collections/logos.json";
addCollection(icons);

<Icon icon="logos:java" />;

🧩 CLI Usage: iconify-downloader

A command-line tool to download icons from Iconify as standalone SVG files or bundled JSON collections.

Usage Example

npx iconify-downloader -i logos:react logos:nodejs -f json -o ./output

🔧 CLI Options

Usage: iconify-downloader [options]

Download icons from Iconify in SVG or JSON format.

Options:
-i, --icons <icons...> Icon names (required), e.g. logos:react skill-icons:javascript
-o, --output <dir>      Output directory (default: "svg-> icons, json -> collections")
-f, --format <format> Output format: svg | json (default: svg)
-h, --help Show help and usage info
-g,--generate [dir] Generate IconLoader (optional: Loader get generated to cwd if no value passed)
-t,--use-typescript [format]  Used along with --generate to use typescript (IconLoader.tsx) Loader

JSON IconLoader

Sample IconLoader

"use client";

import { addCollection } from "@iconify/react";
import logos from "logos.json";

export function IconLoader (){
  addCollection(logos)
  return null;
}

Usage

import IconLoader from "IconLoader";

// before using icons, add Loader to use svg icons from json files
// or add in layout before childrens itself

<IconLoader/>
<Icon icon="mdi:github" width={30} />

Nextjs Example

It may add flickering on icons as it's loaded on client side, better use iconify-nextjs-ssr to render iconify icons as ISR.

// app/layout.tsx

import IconLoader from "IconLoader";

export default function RootLayout({
  children,
}: Readonly<{
  children: React.ReactNode;
}>) {
  return (
    <html lang="en">
      <body >
          <IconLoader />
          {children}
      </body>
    </html>
  );
}

React (vite) Example

// src/main.tsx

import IconLoader from "IconLoader";

createRoot(document.getElementById('root')!).render(
  <StrictMode>
  <IconLoader/>
    <App />
  </StrictMode>,
)