Skip to content

[docs] Improve icon documentation with practical examples #4810

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
christian-byrne merged 2 commits into from
Aug 7, 2025
Merged

[docs] Improve icon documentation with practical examples #4810

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
064f52a
[docs] improve icon documentation with practical examples and clearer…
christian-byrne Aug 7, 2025
c6cb1db
[docs] restore valuable troubleshooting and best practices sections
christian-byrne Aug 7, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 9 additions & 3 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -255,11 +255,17 @@ npm run format
- Add translations to `src/locales/en/main.json`
- Use translation keys: `const { t } = useI18n(); t('key.path')`

## Custom Icons
## Icons

The project supports custom SVG icons through the unplugin-icons system. Custom icons are stored in `src/assets/icons/custom/` and can be used as Vue components with the `i-comfy:` prefix.
The project supports three types of icons, all with automatic imports (no manual imports needed):

For detailed instructions on adding and using custom icons, see [src/assets/icons/README.md](src/assets/icons/README.md).
1. **PrimeIcons** - Built-in PrimeVue icons using CSS classes: `<i class="pi pi-plus" />`
2. **Iconify Icons** - 200,000+ icons from various libraries: `<i-lucide:settings />`, `<i-mdi:folder />`
3. **Custom Icons** - Your own SVG icons: `<i-comfy:workflow />`

Icons are powered by the unplugin-icons system, which automatically discovers and imports icons as Vue components. Custom icons are stored in `src/assets/icons/custom/`.

For detailed instructions and code examples, see [src/assets/icons/README.md](src/assets/icons/README.md).

## Working with litegraph.js

Expand Down
282 changes: 204 additions & 78 deletions src/assets/icons/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,53 +1,148 @@
# ComfyUI Custom Icons Guide
# ComfyUI Icons Guide

This guide explains how to add and use custom SVG icons in the ComfyUI frontend.
ComfyUI supports three types of icons that can be used throughout the interface. All icons are automatically imported - no manual imports needed!

## Overview
## Quick Start - Code Examples

ComfyUI uses a hybrid icon system that supports:
- **PrimeIcons** - Legacy icon library (CSS classes like `pi pi-plus`)
- **Iconify** - Modern icon system with 200,000+ icons
- **Custom Icons** - Your own SVG icons
### 1. PrimeIcons

Custom icons are powered by [unplugin-icons](https://github.com/unplugin/unplugin-icons) and integrate seamlessly with Vue's component system.
```vue
<template>
<!-- Basic usage -->
<i class="pi pi-plus" />
<i class="pi pi-cog" />
<i class="pi pi-check text-green-500" />

<!-- In PrimeVue components -->
<button icon="pi pi-save" label="Save" />
<button icon="pi pi-times" severity="danger" />
</template>
```

## Quick Start
[Browse all PrimeIcons →](https://primevue.org/icons/#list)

### 1. Add Your SVG Icon
### 2. Iconify Icons (Recommended)

Place your SVG file in the `custom/` directory:
```vue
<template>
<!-- Primary icon set: Lucide -->
<i-lucide:download />
<i-lucide:settings />
<i-lucide:workflow class="text-2xl" />

<!-- Other popular icon sets -->
<i-mdi:folder-open />
<!-- Material Design Icons -->
<i-heroicons:document-text />
<!-- Heroicons -->
<i-tabler:brand-github />
<!-- Tabler Icons -->
<i-carbon:cloud-upload />
<!-- Carbon Icons -->

<!-- With styling -->
<i-lucide:save class="w-6 h-6 text-blue-500" />
</template>
```
src/assets/icons/custom/
└── your-icon.svg

[Browse 200,000+ icons →](https://icon-sets.iconify.design/)

### 3. Custom Icons

```vue
<template>
<!-- Your custom SVG icons from src/assets/icons/custom/ -->
<i-comfy:workflow />
<i-comfy:node-tree />
<i-comfy:my-custom-icon class="text-xl" />

<!-- In PrimeVue button -->
<Button severity="secondary">
<template #icon>
<i-comfy:workflow />
</template>
</Button>
</template>
```

### 2. Use in Components
## Icon Usage Patterns

### In Buttons

```vue
<template>
<!-- Use as a Vue component -->
<i-comfy:your-icon />
<!-- In a PrimeVue button -->
<!-- PrimeIcon in button (simple) -->
<Button icon="pi pi-check" label="Confirm" />

<!-- Iconify/Custom in button (template) -->
<Button>
<template #icon>
<i-comfy:your-icon />
<i-lucide:save />
</template>
Save File
</Button>
</template>
```

## SVG Requirements
### Conditional Icons

```vue
<template>
<i-lucide:eye v-if="isVisible" />
<i-lucide:eye-off v-else />

<!-- Or with ternary -->
<component :is="isLocked ? 'i-lucide:lock' : 'i-lucide:lock-open'" />
</template>
```

### With Tooltips

```vue
<template>
<i-lucide:info
v-tooltip="'Click for more information'"
class="cursor-pointer"
/>
</template>
```

## Using Iconify Icons

### Finding Icons

1. Visit [Iconify Icon Sets](https://icon-sets.iconify.design/)
2. Search or browse collections
3. Click on any icon to get its name
4. Use with `i-[collection]:[icon-name]` format

### Popular Collections

### File Naming
- Use kebab-case: `workflow-icon.svg`, `node-tree.svg`
- Avoid special characters and spaces
- The filename becomes the icon name
- **Lucide** (`i-lucide:`) - Our primary icon set, clean and consistent
- **Material Design Icons** (`i-mdi:`) - Comprehensive Material Design icons
- **Heroicons** (`i-heroicons:`) - Beautiful hand-crafted SVG icons
- **Tabler** (`i-tabler:`) - 3000+ free SVG icons
- **Carbon** (`i-carbon:`) - IBM's design system icons

## Adding Custom Icons

### 1. Add Your SVG

Place your SVG file in `src/assets/icons/custom/`:

```
src/assets/icons/custom/
├── workflow-duplicate.svg
├── node-preview.svg
└── your-icon.svg
```

### 2. SVG Format Requirements

### SVG Format
```xml
<svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
<path d="..." />
<!-- Use currentColor for theme compatibility -->
<path fill="currentColor" d="..." />
</svg>
```

Expand All @@ -57,59 +152,98 @@ src/assets/icons/custom/
- Use `currentColor` for theme-aware icons
- Keep SVGs optimized and simple

### Color Theming
### 3. Use Immediately

```vue
<template>
<i-comfy:your-icon />
</template>
```

No imports needed - icons are auto-discovered!

For icons that adapt to the current theme, use `currentColor`:
## Icon Guidelines

### Naming Conventions

- **Files**: `kebab-case.svg` (workflow-icon.svg)
- **Usage**: `<i-comfy:workflow-icon />`

### Size & Styling

```vue
<template>
<!-- Size with Tailwind classes -->
<i-lucide:plus class="w-4 h-4" />
<!-- 16px -->
<i-lucide:plus class="w-6 h-6" />
<!-- 24px (default) -->
<i-lucide:plus class="w-8 h-8" />
<!-- 32px -->

<!-- Or text size -->
<i-lucide:plus class="text-sm" />
<i-lucide:plus class="text-2xl" />

<!-- Colors -->
<i-lucide:check class="text-green-500" />
<i-lucide:x class="text-red-500" />
</template>
```

### Theme Compatibility

Always use `currentColor` in SVGs for automatic theme adaptation:

```xml
<!-- ✅ Good: Uses currentColor -->
<!-- ✅ Good: Adapts to light/dark theme -->
<svg viewBox="0 0 24 24">
<path stroke="currentColor" fill="none" d="..." />
<path fill="currentColor" d="..." />
</svg>

<!-- ❌ Bad: Hardcoded colors -->
<!-- ❌ Bad: Fixed colors -->
<svg viewBox="0 0 24 24">
<path stroke="white" fill="black" d="..." />
<path fill="#000000" d="..." />
</svg>
```

## Usage Examples
## Migration Guide

### Basic Icon
```vue
<i-comfy:workflow />
```
### From PrimeIcons to Iconify/Custom

### With Classes
```vue
<i-comfy:workflow class="text-2xl text-blue-500" />
```
<template>
<!-- Before -->
<Button icon="pi pi-download" />

### In Buttons
```vue
<Button severity="secondary" text>
<template #icon>
<i-comfy:workflow />
</template>
</Button>
<!-- After -->
<Button>
<template #icon>
<i-lucide:download />
</template>
</Button>
</template>
```

### Conditional Icons
### From Inline SVG to Custom Icon

```vue
<template #icon>
<i-comfy:workflow v-if="isWorkflow" />
<i-comfy:node v-else />
<template>
<!-- Before: Inline SVG -->
<svg class="w-6 h-6" viewBox="0 0 24 24">
<path d="..." />
</svg>

<!-- After: Save as custom/my-icon.svg and use -->
<i-comfy:my-icon class="w-6 h-6" />
</template>
```

## Technical Details

### How It Works
### Auto-Import System

1. **unplugin-icons** automatically discovers SVG files in `custom/`
2. During build, SVGs are converted to Vue components
3. Components are tree-shaken - only used icons are bundled
4. The `i-` prefix and `comfy:` namespace identify custom icons
Icons are automatically imported using `unplugin-icons` - no manual imports needed! Just use the icon component directly.

### Configuration

Expand All @@ -119,17 +253,18 @@ The icon system is configured in `vite.config.mts`:
Icons({
compiler: 'vue3',
customCollections: {
'comfy': FileSystemIconLoader('src/assets/icons/custom'),
comfy: FileSystemIconLoader('src/assets/icons/custom')
}
})
```

### TypeScript Support

Icons are automatically typed. If TypeScript doesn't recognize a new icon:
1. Restart your dev server
2. Check that the SVG file is valid
3. Ensure the filename follows kebab-case convention
Icons are fully typed. If TypeScript doesn't recognize a new custom icon:

1. Restart the dev server
2. Ensure the SVG file is valid
3. Check filename follows kebab-case

## Troubleshooting

Expand Down Expand Up @@ -157,22 +292,6 @@ Icons are automatically typed. If TypeScript doesn't recognize a new icon:
4. **Theme support**: Always use `currentColor` for adaptable icons
5. **Test both themes**: Verify icons look good in light and dark modes

## Migration from PrimeIcons

When replacing a PrimeIcon with a custom icon:

```vue
<!-- Before: PrimeIcon -->
<Button icon="pi pi-box" />

<!-- After: Custom icon -->
<Button>
<template #icon>
<i-comfy:workflow />
</template>
</Button>
```

## Adding Icon Collections

To add an entire icon set from npm:
Expand All @@ -181,4 +300,11 @@ To add an entire icon set from npm:
2. Configure in `vite.config.mts`
3. Use with the appropriate prefix

See the [unplugin-icons documentation](https://github.com/unplugin/unplugin-icons) for details.
See the [unplugin-icons documentation](https://github.com/unplugin/unplugin-icons) for details.

## Resources

- [PrimeIcons List](https://primevue.org/icons/#list)
- [Iconify Icon Browser](https://icon-sets.iconify.design/)
- [Lucide Icons](https://lucide.dev/icons/)
- [unplugin-icons docs](https://github.com/unplugin/unplugin-icons)