Heroicons is a curated collection of free, MIT-licensed, high-quality SVG icons designed for UI development. This guide provides quick solutions for common problems encountered during Heroicons integration.

1. Icons Not Displaying: Incorrect Path Reference

Symptom: Blank spaces or placeholders appear where icons should be.

Solution: Verify that icon paths are correctly referenced. Heroicons SVG files are typically organized as folllows:

• 16x16px: optimized/16/solid/
• 20x20px: optimized/20/solid/
• 24x24px: optimized/24/ (includes both outline and solid styles)

Ensure your import statements match the file system structure. For example, to use a 24x24px solid icon, import from optimized/24/solid/[icon_name].svg.

2. React Project Import Errors: Module Not Found

Symptom: Console shows Module not found: Error: Can't resolve 'heroicons/react'.

Solution:

1. Confirm Heroicons is installed for React: ``` npm install @heroicons/react

2. Use the correct import syntax (example for a 24x24px solid icon): ``` import { BellIcon } from '@heroicons/react/24/solid'

3. Vue Project Icon Rendering Issues: Component Registration Problem

Symptom: Icons do not render when used as components in Vue templates.

Solution:

1. Install the dedicated Vue package: ``` npm install @heroicons/vue

2. Register and use the component correctly within your Vue component: ```

4. Icon Size Mismatch: Incorrect Dimensions

Symptom: Icons appear larger or smaller than intended.

Solution:

• Heroicons offers fixed sizes: 16x16px, 20x20px, and 24x24px.
• Control the display size using CSS. For a 24x24px icon: ``` .icon { width: 32px; /* Adjust as needed */ height: 32px; }

• Avoid setting conflicting width and height values simultaneously to prevent distortion.

5. Icon Color Not Applied: Style Override Issues

Symptom: Setting the color CSS property does not change the icon's color.

Solution:

• SVG icons default to inheriting the parent element's text color via currentColor.
• Ensure no hardcoded fill attributes exist within the SVG file (optimized Heroicons typically omit these).
• Apply styles correctly: ``` .icon-primary { color: #3b82f6; /* Example: Blue */ }

6. Build Tool Errors: SVG Loading Failures

Symptom: Build tools like Webpack or Vite report errors when loading SVG files.

Solution:

1. Configure your build tool to support SVG imports. For Vite: ``` // vite.config.js export default defineConfig({ assetsInclude: ['**/*.svg'] })

2. Alternatively, use Heroicons' official component packages to bypass manual SVG handling.

7. Icon Name Confusion: Version Discrepancies

Symptom: Errors like "file not found" ocurr when referencing certain icons.

Solution:

• Check your Heroicons version, as icon names may change between versions.
• Consult the CHANGELOG.md file in the project root for icon name changes.
• Updating to latest version can resolve compatibility issues: ``` npm update @heroicons/react

8. Browser Compatibility: Older Browser Support

Symptom: Icons display incorrectly in older browsers like Internet Explorer.

Solution:

• For projects requiring IE support, consider using @heroicons/react@1.x.
• Include an SVG polyfill: ```

• As a fallback, consider using PNG versions of the icons.

9. Large Bundle Size: Lack of Tree-Shaking

Symptom: The final built project size is unexpectedly large.

Solution:

• Import icons on demand rather than importing the entire library: ``` // Recommended: Import only necessary icons import { BellIcon, SearchIcon } from '@heroicons/react/24/solid'

    // Not recommended: Importing all icons
    import * as Heroicons from '@heroicons/react/24/solid'
  

• For projects using raw SVG files, employ optimization tools like svgo. The project may provide configuration files (e.g., svgo.24.solid.mjs).

10. Icon Style Conflicts: Design System Incompatibility

Symptom: Icons do not align with the project's design system styles.

Solution:

• Use CSS variables for consistent icon styling: ``` :root { --icon-size: 24px; --icon-color: currentColor; --icon-stroke-width: 2px; /* For outline style only */ }

  .heroicon { width: var(--icon-size); height: var(--icon-size); color: var(--icon-color); }

• For outline icons, the stroke-width attribute can be adjusted to control line thickness.

Best Practices for Efficient Heroicons Usage

1. Choose the appropriate integration method: component libraries (React/Vue) or direct SVG usage.
2. Keep Heroicons updated and monitor the CHANGELOG.md for changes.
3. Establish project-specific guidelines for icon usage, standardizing size and style application.
4. Utilize provided utility scripts (e.g., scripts/verify-names.js) to validate icon references.

By following these solutions and best practices, you can mitigate most common Heroicons integration issues, leading to a smoother development workflow.