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