> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/react-icons/react-icons/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions to common issues when using React Icons

# Troubleshooting Guide

Find solutions to common problems when using React Icons.

## Installation Issues

### Package Installation Fails

<Accordion title="npm install fails with permission errors">
  **Problem:** Permission denied errors when installing

  **Solution:**

  ```bash theme={null}
  # Don't use sudo with npm
  # Instead, fix npm permissions:
  npm config set prefix ~/.npm-global
  export PATH=~/.npm-global/bin:$PATH

  # Then install normally
  npm install react-icons
  ```

  Or use a version manager like [nvm](https://github.com/nvm-sh/nvm).
</Accordion>

<Accordion title="Yarn install fails with network errors">
  **Problem:** Network timeouts or connection errors

  **Solution:**

  ```bash theme={null}
  # Try with different registry
  yarn add react-icons --registry https://registry.npmjs.org

  # Or clear cache and retry
  yarn cache clean
  yarn add react-icons
  ```
</Accordion>

<Accordion title="Module not found after installation">
  **Problem:** `Cannot find module 'react-icons'`

  **Solution:**

  1. Verify installation:

  ```bash theme={null}
  ls node_modules/react-icons
  ```

  2. If missing, reinstall:

  ```bash theme={null}
  rm -rf node_modules package-lock.json
  npm install
  ```

  3. Check import path:

  ```jsx theme={null}
  // ✅ Correct
  import { FaBeer } from "react-icons/fa";

  // ❌ Wrong
  import { FaBeer } from "react-icons";
  ```
</Accordion>

## Import & Build Issues

### Icons Not Rendering

<Accordion title="Icons show as empty elements">
  **Problem:** Icons don't appear but no errors in console

  **Diagnosis:**

  ```jsx theme={null}
  import { FaBeer } from "react-icons/fa";

  console.log(FaBeer); // Should log a function
  console.log(typeof FaBeer); // Should be "function"
  ```

  **Solutions:**

  1. **Check import syntax:**

  ```jsx theme={null}
  // ✅ Correct
  import { FaBeer } from "react-icons/fa";

  // ❌ Wrong
  import FaBeer from "react-icons/fa/FaBeer";
  ```

  2. **Verify icon name is correct:**

  ```jsx theme={null}
  // Check icon exists
  import * as FaIcons from "react-icons/fa";
  console.log(Object.keys(FaIcons)); // List all available icons
  ```

  3. **Ensure React is imported:**

  ```jsx theme={null}
  import React from "react";  // Required in older React versions
  import { FaBeer } from "react-icons/fa";
  ```
</Accordion>

<Accordion title="SVG not visible (size is 0)">
  **Problem:** Icon renders but has no size

  **Solution:**

  ```jsx theme={null}
  // Set explicit size
  <FaBeer size={24} />

  // Or use CSS
  <FaBeer style={{ width: 24, height: 24 }} />
  <FaBeer className="w-6 h-6" />
  ```

  Icons default to `1em` - ensure parent has font-size set:

  ```css theme={null}
  .parent {
    font-size: 16px;  /* Icons will be 16px */
  }
  ```
</Accordion>

### Bundle Size Issues

<Accordion title="Bundle size is too large">
  **Problem:** Bundle includes many unused icons

  **Diagnosis:**

  Analyze your bundle:

  ```bash theme={null}
  # For Create React App
  npm install --save-dev source-map-explorer
  npm run build
  npx source-map-explorer 'build/static/js/*.js'

  # For Next.js
  npm install --save-dev @next/bundle-analyzer
  ```

  **Common causes & fixes:**

  1. **Importing entire library:**

  ```jsx theme={null}
  // ❌ Wrong - imports everything (~2MB)
  import * as Icons from "react-icons/fa";

  // ✅ Correct - only imports needed icons
  import { FaBeer, FaCoffee } from "react-icons/fa";
  ```

  2. **Dynamic imports with wildcard:**

  ```jsx theme={null}
  // ❌ Wrong
  const icon = Icons[`Fa${iconName}`];

  // ✅ Better - explicit mapping
  const iconMap = {
    beer: FaBeer,
    coffee: FaCoffee
  };
  const Icon = iconMap[iconName];
  ```

  3. **Bundler not tree-shaking:**

  **Webpack 5:**

  ```js webpack.config.js theme={null}
  module.exports = {
    mode: 'production',
    optimization: {
      usedExports: true,
      sideEffects: false
    }
  };
  ```

  **Vite** - works by default

  **Create React App** - works by default in production builds

  See [Performance Optimization](/guides/performance) for more tips.
</Accordion>

<Accordion title="Tree-shaking not working">
  **Problem:** All icons from a pack are included

  **Check:**

  1. **Using production build:**

  ```bash theme={null}
  # Development builds don't tree-shake
  NODE_ENV=production npm run build
  ```

  2. **Module format:**

  ```json package.json theme={null}
  {
    "type": "module"  // Helps with tree-shaking
  }
  ```

  3. **Bundler configuration:**

  For Webpack:

  ```js theme={null}
  module.exports = {
    optimization: {
      usedExports: true,
    },
  };
  ```

  4. **Import from correct path:**

  ```jsx theme={null}
  // ✅ ES module path (tree-shakeable)
  import { FaBeer } from "react-icons/fa";

  // ❌ CommonJS path (not tree-shakeable)
  const { FaBeer } = require("react-icons/fa");
  ```
</Accordion>

## TypeScript Issues

<Accordion title="Type errors with icon imports">
  **Problem:** TypeScript can't find types

  **Solution:**

  1. **Remove conflicting types:**

  ```bash theme={null}
  npm uninstall @types/react-icons
  ```

  React Icons v3+ includes native TypeScript support.

  2. **Update TypeScript:**

  ```bash theme={null}
  npm install --save-dev typescript@latest
  ```

  Requires TypeScript 4.0+

  3. **Check tsconfig.json:**

  ```json theme={null}
  {
    "compilerOptions": {
      "esModuleInterop": true,
      "moduleResolution": "node"
    }
  }
  ```
</Accordion>

<Accordion title="IconType not working">
  **Problem:** `IconType` type errors

  **Solution:**

  ```tsx theme={null}
  import { IconType } from "react-icons";

  type Props = {
    icon: IconType;  // ✅ Correct
    size?: number;
  };

  function IconWrapper({ icon: Icon, size }: Props) {
    return <Icon size={size} />;
  }
  ```

  Make sure to destructure and capitalize:

  ```tsx theme={null}
  // ✅ Correct - Icon is capitalized
  const { icon: Icon } = props;
  return <Icon />;

  // ❌ Wrong - lowercase won't work
  const { icon } = props;
  return <icon />;  // Error: 'icon' is not a JSX component
  ```
</Accordion>

<Accordion title="Type 'Element' is not assignable to type 'ReactNode'">
  **Problem:** Type mismatch in strict mode

  **Solution:**

  ```tsx theme={null}
  import { ReactElement } from "react";
  import { IconType } from "react-icons";

  type Props = {
    icon: IconType;
  };

  function Component({ icon: Icon }: Props): ReactElement {
    return <Icon />;
  }
  ```
</Accordion>

## Framework-Specific Issues

### Next.js

<Accordion title="Icons not rendering in Next.js App Router">
  **Problem:** Icons don't show in Server Components

  **Solution:**

  Icons work in Server Components, but IconContext needs Client Component:

  ```jsx app/icon-provider.jsx theme={null}
  "use client";
  import { IconContext } from "react-icons";

  export function IconProvider({ children }) {
    return (
      <IconContext.Provider value={{ size: "1.5em" }}>
        {children}
      </IconContext.Provider>
    );
  }
  ```

  ```jsx app/layout.jsx theme={null}
  import { IconProvider } from "./icon-provider";

  export default function RootLayout({ children }) {
    return (
      <html>
        <body>
          <IconProvider>{children}</IconProvider>
        </body>
      </html>
    );
  }
  ```
</Accordion>

<Accordion title="Build fails with 'Cannot find module'">
  **Problem:** Next.js build fails importing icons

  **Solution:**

  1. **Check Next.js version:**

  ```bash theme={null}
  npm install next@latest
  ```

  Requires Next.js 12+

  2. **Verify import paths:**

  ```jsx theme={null}
  // ✅ Correct
  import { FaBeer } from "react-icons/fa";

  // ❌ Wrong - don't import from lib/
  import { FaBeer } from "react-icons/lib/fa";
  ```
</Accordion>

### Create React App

<Accordion title="Icons not updating after build">
  **Problem:** Changes to icons don't reflect in build

  **Solution:**

  ```bash theme={null}
  # Clear cache and rebuild
  rm -rf node_modules/.cache
  npm run build
  ```
</Accordion>

### Vite

<Accordion title="Import errors with Vite">
  **Problem:** `Failed to resolve import`

  **Solution:**

  Vite works with React Icons by default. If you see errors:

  ```js vite.config.js theme={null}
  import { defineConfig } from 'vite';
  import react from '@vitejs/plugin-react';

  export default defineConfig({
    plugins: [react()],
    optimizeDeps: {
      include: ['react-icons']  // Pre-bundle react-icons
    }
  });
  ```
</Accordion>

## Styling Issues

<Accordion title="Icons misaligned with text">
  **Problem:** Icons don't align vertically with text

  **Solution:**

  React Icons v3+ removed automatic alignment. Add it back:

  ```jsx theme={null}
  // Global fix
  import { IconContext } from "react-icons";

  <IconContext.Provider value={{ style: { verticalAlign: 'middle' } }}>
    <YourApp />
  </IconContext.Provider>
  ```

  ```jsx theme={null}
  // Per icon
  <FaBeer style={{ verticalAlign: 'middle' }} />
  ```

  ```css theme={null}
  /* CSS class */
  .icon {
    vertical-align: middle;
  }
  ```

  See [Migration v2 to v3](/migration/v2-to-v3) for details.
</Accordion>

<Accordion title="Icons don't respond to color prop">
  **Problem:** Color prop doesn't work

  **Check:**

  1. **Not using multiColor icons:**

  ```jsx theme={null}
  // Flat Color Icons preserve original colors
  import { FcIdea } from "react-icons/fc";
  <FcIdea color="red" /> {/* Won't work - colors are fixed */}
  ```

  2. **CSS specificity:**

  ```css theme={null}
  /* Overly specific CSS */
  svg path {
    fill: blue !important;  /* Overrides color prop */
  }
  ```

  **Solution:**

  ```jsx theme={null}
  // Use currentColor
  <div style={{ color: "red" }}>
    <FaBeer />  {/* Inherits red */}
  </div>
  ```
</Accordion>

<Accordion title="Tailwind classes not working">
  **Problem:** Tailwind CSS classes have no effect

  **Solution:**

  ```jsx theme={null}
  // Size classes need to be explicit
  <FaBeer className="w-6 h-6" />  {/* ✅ Works */}

  // Or use size prop
  <FaBeer size={24} className="text-blue-500" />  {/* ✅ Works */}
  ```

  Note: Tailwind's size utilities override the icon's default `1em` size.
</Accordion>

## Context API Issues

<Accordion title="IconContext not applying styles">
  **Problem:** Context values don't affect icons

  **Check:**

  1. **Icons are inside Provider:**

  ```jsx theme={null}
  import { IconContext } from "react-icons";

  // ✅ Correct
  <IconContext.Provider value={{ color: "blue" }}>
    <FaBeer />  {/* Will be blue */}
  </IconContext.Provider>

  // ❌ Wrong - icon outside provider
  <FaBeer />  {/* Won't be blue */}
  <IconContext.Provider value={{ color: "blue" }}>
    {children}
  </IconContext.Provider>
  ```

  2. **Props override context:**

  ```jsx theme={null}
  <IconContext.Provider value={{ color: "blue" }}>
    <FaBeer color="red" />  {/* Will be red, not blue */}
  </IconContext.Provider>
  ```
</Accordion>

<Accordion title="Nested contexts not working correctly">
  **Problem:** Inner context doesn't override outer

  **Expected behavior:**

  ```jsx theme={null}
  <IconContext.Provider value={{ color: "blue", size: 24 }}>
    <FaBeer />  {/* blue, size 24 */}
    
    <IconContext.Provider value={{ color: "red" }}>
      <FaCoffee />  {/* red, size 24 (size inherited) */}
    </IconContext.Provider>
  </IconContext.Provider>
  ```

  Inner contexts merge with outer contexts, with inner values taking precedence.
</Accordion>

## Error Messages

<Accordion title="Warning: React does not recognize prop">
  **Problem:** `Warning: React does not recognize the 'size' prop on a DOM element`

  **Cause:** Passing icon props to wrong element

  **Solution:**

  ```jsx theme={null}
  // ❌ Wrong - size on div
  <div size={24}>
    <FaBeer />
  </div>

  // ✅ Correct - size on icon
  <div>
    <FaBeer size={24} />
  </div>
  ```
</Accordion>

<Accordion title="Element type is invalid">
  **Problem:** `Error: Element type is invalid: expected a string or a class/function`

  **Cause:** Import failed or component not capitalized

  **Solution:**

  ```tsx theme={null}
  import { IconType } from "react-icons";
  import { FaBeer } from "react-icons/fa";

  type Props = { icon: IconType };

  function Component({ icon: Icon }: Props) {
    // ✅ Correct - Icon is capitalized
    return <Icon />;
    
    // ❌ Wrong - lowercase
    // return <icon />;
  }
  ```
</Accordion>

## Getting More Help

<CardGroup cols={2}>
  <Card title="FAQ" icon="circle-question" href="/resources/faq">
    Check frequently asked questions
  </Card>

  <Card title="GitHub Issues" icon="circle-exclamation" href="https://github.com/react-icons/react-icons/issues">
    Search existing issues or report a bug
  </Card>

  <Card title="GitHub Discussions" icon="comments" href="https://github.com/react-icons/react-icons/discussions">
    Ask the community for help
  </Card>

  <Card title="Stack Overflow" icon="stack-overflow" href="https://stackoverflow.com/questions/tagged/react-icons">
    Search or ask questions
  </Card>
</CardGroup>

<Tip>
  When asking for help, include:

  * React Icons version (`npm list react-icons`)
  * React version
  * Framework (Next.js, CRA, Vite, etc.) and version
  * Code example showing the issue
  * Error messages (if any)
</Tip>