Managing SVG Icons with Denji

Denji converts Iconify SVG icons into typed framework components. Icons are fetched, optimized (SVGO), and generated as native components for your framework.

Core Workflow

# 1. Initialize project
npx denji init --framework react --output ./src/icons.tsx

# 2. Add icons (prefix:name format from Iconify)
npx denji add lucide:check lucide:x lucide:arrow-right

# 3. Use in your code

import { Icons } from "./icons";

<Icons.Check className="size-4 text-green-500" />
<Icons.X className="size-4 text-red-500" />

Commands

denji init

Initialize a Denji project. Creates denji.json config and icons template.

npx denji init
npx denji init --framework react --output ./src/icons.tsx
npx denji init --framework svelte --output ./src/icons --output-type folder
npx denji init --framework react --no-typescript --output ./src/icons.jsx
npx denji init --a11y hidden --forward-ref

Flag	Description
--framework <name>	react, preact, solid, qwik, vue, svelte
--output <path>	Output path for icons file/folder
--output-type <type>	file (single file) or folder (one file per icon)
--typescript / --no-typescript	TypeScript or JavaScript (default: TS)
--a11y <strategy>	hidden, img, title, presentation, or false (no a11y attrs)
--forward-ref / --no-forward-ref	Use forwardRef (React/Preact only)
--track-source / --no-track-source	Track Iconify source via data-icon attr
-c, --cwd <path>	Working directory

Missing flags trigger interactive prompts.

denji add <icons...>

Add icons from Iconify. Icons use prefix:name format.

npx denji add lucide:check
npx denji add lucide:check mdi:home radix-icons:cross-2
npx denji add lucide:star --name FavoriteStar
npx denji add lucide:info --a11y img
# Preview without writing files
npx denji add lucide:check mdi:home --dry-run

Flag	Description
--name <name>	Custom component name (single icon only)
--a11y <strategy>	Override a11y strategy for this icon
--dry-run	Preview what would be generated without writing any files
-c, --cwd <path>	Working directory

Icon naming: lucide:arrow-right becomes ArrowRight (PascalCase). Override with --name.

Adding an existing icon updates it in place.

--dry-run skips file writes and hooks but still validates icon names, allowedLibraries, and config. Useful for CI checks and PR previews.

◇ denji add
│
○ [dry-run] Would add Check → ./src/icons.tsx
○ [dry-run] Would add Home → ./src/icons.tsx
│
◇ Dry run complete — 2 icon(s) previewed, no files written

denji remove <icons...>

Remove icons by component name. Aliases: rm, delete, del.

npx denji remove Check
npx denji rm Check Home ArrowRight

Flag	Description
-c, --cwd <path>	Working directory

denji list

List all icons in your project.

npx denji list
npx denji list --display json
npx denji list --display toon

Flag	Description
--display <mode>	Output mode: default (human-readable), json, or toon
-c, --cwd <path>	Working directory

Shows component names and Iconify source (if trackSource: true).

Default output:

Found 3 icon(s) in ./src/icons.tsx

Icons:
  • Check (lucide:check)
  • HomeOutline (mdi:home-outline)
  • ArrowRight (lucide:arrow-right)

JSON output (--display json):

{
  "count": 3,
  "output": "./src/icons.tsx",
  "icons": [
    { "name": "Check", "source": "lucide:check" },
    { "name": "HomeOutline", "source": "mdi:home-outline" },
    { "name": "ArrowRight", "source": "lucide:arrow-right" }
  ]
}

TOON output (--display toon) uses TOON format for machine-readable binary encoding.

denji export

Export a JSON manifest of all tracked icons.

npx denji export                    # print to stdout
npx denji export --output icons.json
npx denji export --output           # writes to denji-export.json

Flag	Description
--output [path]	Write to file (default: denji-export.json if no path given)
-c, --cwd <path>	Working directory

Output format:

{
  "version": 1,
  "framework": "react",
  "output": "./src/icons.tsx",
  "icons": [
    { "name": "Home", "source": "mdi:home" },
    { "name": "Check", "source": "lucide:check" }
  ]
}

source is included only when trackSource: true (the default).

denji import

Bulk-add icons from a manifest JSON file, a plain text file, or stdin.

npx denji import icons.json         # from denji export manifest
npx denji import icons.txt          # one prefix:name per line
echo "mdi:home\nlucide:check" | npx denji import   # from stdin
npx denji import icons.json --dry-run

Flag	Description
--dry-run	Preview without writing files
-c, --cwd <path>	Working directory

Icons without prefix:name format are skipped with a warning. JSON manifest entries without a source field are also skipped.

denji clear

Remove all icons. Aliases: clr, reset.

npx denji clear
npx denji clear --yes

Flag	Description
-y, --yes	Skip confirmation prompt
-c, --cwd <path>	Working directory

Config (denji.json)

The $schema field depends on how Denji is installed:

• Locally installed (npm i -D denji): "./node_modules/denji/configuration_schema.json"
• Not installed (using npx, bunx, pnpx, yarn dlx): "https://denji-docs.vercel.app/configuration_schema.json"

{
  "$schema": "./node_modules/denji/configuration_schema.json",
  "framework": "react",
  "output": "./src/icons.tsx",
  "typescript": true,
  "a11y": "hidden",
  "trackSource": true,
  "allowedLibraries": ["lucide"],
  "react": {
    "forwardRef": true
  },
  "hooks": {
    "postAdd": ["npx biome check --write ./src/icons.tsx"],
    "postRemove": ["npx biome check --write ./src/icons.tsx"]
  }
}

Key fields:

Field	Type	Description
framework	string	Required. react, preact, solid, qwik, vue, svelte
output	string or object	Required. Path string or { type: "file"|"folder", path: "..." }
typescript	boolean	Default: true
a11y	string or false	hidden, img, title, presentation, false
trackSource	boolean	Default: true. Adds data-icon attr
allowedLibraries	string[]	Restrict to specific Iconify prefixes. Empty/omitted = all allowed
hooks	object	Lifecycle hooks (see below)

Output Modes

File mode (default for React, Preact, Solid, Qwik, Vue): All icons in one file.

{ "output": "./src/icons.tsx" }

Folder mode (required for Svelte, optional for others): One file per icon + barrel export.

{ "output": { "type": "folder", "path": "./src/icons" } }

Hooks

Run shell commands at lifecycle points:

{
  "hooks": {
    "preAdd": ["echo 'Adding icons...'"],
    "postAdd": ["npx prettier --write ./src/icons.tsx"],
    "preRemove": [],
    "postRemove": [],
    "preClear": [],
    "postClear": [],
    "preList": [],
    "postList": []
  }
}

Common Patterns

Dynamic Icons

import { Icons, type IconName, type IconProps } from "./icons";

function DynamicIcon({ name, ...props }: { name: IconName } & IconProps) {
  const Icon = Icons[name];
  return <Icon {...props} />;
}

<DynamicIcon name="Check" className="size-4" />

Accessibility

// Decorative icon (hidden from screen readers)
<button>
  <Icons.Check aria-hidden="true" />
  Save
</button>

// Semantic icon (announced by screen readers)
<Icons.Check role="img" aria-label="Success" />

// Icon-only button
<button aria-label="Close">
  <Icons.X aria-hidden="true" />
</button>

Restricting Icon Sources

{
  "allowedLibraries": ["lucide"]
}

npx denji add lucide:check   # ✓ allowed
npx denji add mdi:home       # ✗ Error: Icon "mdi:home" is not allowed. Allowed libraries: lucide

Formatting with Hooks

{
  "hooks": {
    "postAdd": ["npx biome check --write ./src/icons.tsx"],
    "postRemove": ["npx biome check --write ./src/icons.tsx"]
  }
}

Using forwardRef (React/Preact)

{
  "framework": "react",
  "react": { "forwardRef": true }
}

const ref = useRef<SVGSVGElement>(null);
<Icons.Check ref={ref} className="size-4" />

Framework Quick Reference

Framework	Extensions	Default Output	Config Key	Notes
React	.tsx/.jsx	file	react	forwardRef option
Preact	.tsx/.jsx	file	preact	forwardRef option (via preact/compat)
Solid	.tsx/.jsx	file	solid	Refs work natively as props
Qwik	.tsx/.jsx	file	qwik	Uses component$() in folder mode
Vue	.ts/.js	file	vue	Uses h() render functions
Svelte	.svelte	folder (only)	svelte	Svelte 5 $props() runes

Deep-Dive References

Reference	Content
references/configuration.md	Full config schema, all framework options, output normalization
references/framework-patterns.md	Per-framework code examples, file vs folder imports, TypeScript types