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

Changes from 1 commit
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
Prev Previous commit
[docs] restore valuable troubleshooting and best practices sections
  • Loading branch information
@christian-byrne
christian-byrne committed Aug 7, 2025
commit c6cb1db176da1a840423745518478de9f5faccfc
47 changes: 34 additions & 13 deletions src/assets/icons/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -146,6 +146,12 @@ src/assets/icons/custom/
</svg>
```

**Important:**
- Use `viewBox` for proper scaling (24x24 is standard)
- Don't include `width` or `height` attributes
- Use `currentColor` for theme-aware icons
- Keep SVGs optimized and simple

### 3. Use Immediately

```vue
Expand Down Expand Up @@ -262,24 +268,39 @@ Icons are fully typed. If TypeScript doesn't recognize a new custom icon:

## Troubleshooting

### Icon Not Showing?
### Icon Not Showing
1. **Check filename**: Must be kebab-case without special characters
2. **Restart dev server**: Required after adding new icons
3. **Verify SVG**: Ensure it's valid SVG syntax
4. **Check console**: Look for Vue component resolution errors

### Icon Wrong Color
- Replace hardcoded colors with `currentColor`
- Use `stroke="currentColor"` for outlines
- Use `fill="currentColor"` for filled shapes

### Icon Wrong Size
- Remove `width` and `height` from SVG
- Ensure `viewBox` is present
- Use CSS classes for sizing: `class="w-6 h-6"`

## Best Practices

1. **Check the name**: Typos in collection or icon name
2. **Restart dev server**: Required after adding custom icons
3. **Verify format**: `i-[collection]:[name]`
4. **Check console**: Look for component errors
1. **Optimize SVGs**: Use tools like [SVGO](https://jakearchibald.github.io/svgomg/) to minimize file size
2. **Consistent viewBox**: Stick to 24x24 or 16x16 for consistency
3. **Semantic names**: Use descriptive names like `workflow-duplicate` not `icon1`
4. **Theme support**: Always use `currentColor` for adaptable icons
5. **Test both themes**: Verify icons look good in light and dark modes

### Wrong Size/Color?
## Adding Icon Collections

- Use Tailwind classes: `class="w-6 h-6 text-blue-500"`
- Ensure SVG uses `currentColor`
- Remove hardcoded width/height from SVG
To add an entire icon set from npm:

### Custom Icon Issues?
1. Install the icon package
2. Configure in `vite.config.mts`
3. Use with the appropriate prefix

- Filename must be `kebab-case.svg`
- Must have valid `viewBox`
- Should use `currentColor` for fills/strokes
See the [unplugin-icons documentation](https://github.com/unplugin/unplugin-icons) for details.

## Resources

Expand Down