Troubleshooting: Common Issues

When integrating and using HugeIcons in your projects, you might encounter some common issues. This guide aims to address these problems, providing solutions to ensure a smooth experience with HugeIcons.

Icons Not Rendering

Symptoms:

• Icons do not appear in your application.
• Icons are replaced by a blank space or broken image icon.

Solutions:

1. Check Package Installation: Ensure you have installed both the framework component package and at least one icon style package:

# Install the framework package (e.g., React)
npm install @hugeicons/react
 
# Install at least one icon style package
npm install @hugeicons-pro/core-stroke-rounded

2. Verify Imports: Make sure you're importing both the framework component and icons correctly:

// Import the framework component
import { HugeiconsIcon } from '@hugeicons/react';
 
// Import the icon
import { SearchIcon } from '@hugeicons-pro/core-stroke-rounded';

3. Check Component Usage: Ensure you're using the component correctly with required props:

<HugeiconsIcon
  icon={SearchIcon}
  size={24}
  color="currentColor"
/>

Icons Displaying Incorrectly

Symptoms:

• Icons appear distorted, wrong color, or wrong size
• Stroke width issues with line icons
• Two-tone colors not showing correctly

Solutions:

1. Check Props: Verify the props being passed to the icon component:

   • size: Should be a number (default: 24)
   • color: Should be a valid CSS color value
   • strokeWidth: Only works with stroke-style icons (default: 1.5)

2. Style Package Compatibility: Ensure you're using the correct props for your icon style:

   • Stroke icons: Can use strokeWidth
   • Solid icons: Ignore strokeWidth
   • Two-tone/Duotone: May require specific color handling

3. CSS Conflicts: Check for CSS rules that might override icon styles:

/* Avoid generic SVG styles that might affect icons */
svg {
  width: auto;
  height: auto;
}

Performance Issues

Symptoms:

• Slow loading times
• Large bundle sizes
• Performance degradation with many icons

Solutions:

1. Optimize Imports: Import only the specific icons you need:

// Good - specific import
import { SearchIcon } from '@hugeicons-pro/core-stroke-rounded';
 
// Bad - importing entire package
import * from '@hugeicons-pro/core-stroke-rounded';

2. Use Dynamic Imports: For icons not needed immediately:

const SearchIcon = dynamic(() => 
  import('@hugeicons-pro/core-stroke-rounded').then(mod => mod.SearchIcon)
)

3. Bundle Size Management:
   • Use a single style package when possible
   • Leverage tree shaking by using named imports
   • Monitor bundle size with tools like webpack-bundle-analyzer

Framework-Specific Issues

If you're experiencing framework-specific issues, please refer to our dedicated integration guides:

• React
• Vue
• Angular
• Svelte
• React Native

TypeScript Module Resolution Issues

Cannot find module '@hugeicons-pro/core-*' or its corresponding type declarations

Error Message:

Cannot find module '@hugeicons-pro/core-solid-rounded' or its corresponding type declarations.
There are types at '.../node_modules/@hugeicons-pro/core-solid-rounded/dist/types/index.d.ts', but this result could not be resolved under your current 'moduleResolution' setting.

Solution:

Update your tsconfig.json to use modern module resolution:

{
  "compilerOptions": {
    "module": "ESNext",
    "moduleResolution": "bundler"
  }
}

Alternatively, you can use "node16" or "nodenext" for the moduleResolution setting.

This issue occurs because the package uses modern ESM module resolution, which requires TypeScript to be configured appropriately. The older "node" module resolution strategy doesn't handle some modern package patterns correctly.