Phosphor React Icons

Common errors

• Named export 'Envelope' not found. The requested module '@phosphor-icons/react' is a CommonJS module, which may not support all module.exports as named exports.

  cause Attempting to import named exports from `@phosphor-icons/react` in a context where the bundler or runtime treats it as a CommonJS module, or an older bundler struggles with its ESM nature.
  fix Ensure your project's bundler is configured to correctly handle ES Modules. If encountering this in Node.js, ensure your package.json has `"type": "module"` or use a transpiler. Sometimes `import pkg from '@phosphor-icons/react'; const { Envelope } = pkg;` can be a workaround for specific bundler issues, but it's not the recommended long-term solution. Upgrade to `@phosphor-icons/react@^2.1.10`.

• Property 'children' does not exist on type 'IntrinsicAttributes & SVGProps<SVGSVGElement> & IconProps'

  cause Type incompatibility between `@phosphor-icons/react`'s internal types and an outdated `@types/react` dependency in your project.
  fix Update `@types/react` to the latest compatible version using `npm install @types/react@latest` or `yarn upgrade @types/react`. This specific issue was addressed and fixed in `v2.1.7`.

• Module not found: Can't resolve '@phosphor-icons/react'

  cause The package `@phosphor-icons/react` is not installed, or the import path is incorrect, or the old package name `phosphor-react` is still being used.
  fix Verify the package is installed with `npm install @phosphor-icons/react` or `yarn add @phosphor-icons/react`. Double-check the import statements to ensure they use `@phosphor-icons/react` as the package name, not `phosphor-react`.

Warnings

• breaking The package name was changed from `phosphor-react` to `@phosphor-icons/react` in v2. Importing from the old package name will result in using an older, unmaintained version and will not receive new icons or updates.
  Fix: Update your `package.json` and imports to use `@phosphor-icons/react`. Run `npm uninstall phosphor-react && npm install @phosphor-icons/react` or `yarn remove phosphor-react && yarn add @phosphor-icons/react`.
• deprecated As of `v2.1.8`, all exported icon components are suffixed with the word 'Icon' (e.g., `UserIcon`). While old names (e.g., `User`) are still valid, they are marked as deprecated to improve readability and prevent name collisions.
  Fix: Update your imports and JSX usage to use the `Icon` suffix, e.g., `import { UserIcon } from '@phosphor-icons/react'` and `<UserIcon />`.
• gotcha When using Phosphor Icons within React Server Components (RSC) or environments that do not permit the Context API (like Next.js Server Components), icons must be imported from the `@phosphor-icons/react/ssr` submodule. These SSR variants do not support `IconContext` inheritance.
  Fix: For RSC usage, change imports from `import { IconName } from '@phosphor-icons/react'` to `import { IconName } from '@phosphor-icons/react/ssr'`.
• gotcha Early v2 versions (before `v2.1.10`) sometimes encountered module resolution issues, especially in mixed ESM/CJS environments, potentially leading to errors like `ReferenceError: exports is not defined` or `SyntaxError: Cannot use import statement outside a module`.
  Fix: Upgrade to `@phosphor-icons/react@^2.1.10` or later, which explicitly adds `"type": "module"` to `package.json` for more predictable bundler behavior. Ensure your bundler is correctly configured for ESM.
• gotcha `v2.1.0` through `v2.1.4` briefly switched to a modern JSX runtime, causing compatibility issues with `react@16` applications. This was reverted in `v2.1.5` to restore React 16 support.
  Fix: If targeting `react@16`, ensure you are using `@phosphor-icons/react@2.1.5` or newer. Alternatively, if locked to affected versions, configure your build system (e.g., Babel, TypeScript) to use the `classic` JSX runtime.

Install

• npm install phosphor-react npm
• yarn add phosphor-react yarn
• pnpm add phosphor-react pnpm

Imports

• HeartIcon
  wrong:

  import { Heart } from 'phosphor-react'

  correct:

  import { HeartIcon } from '@phosphor-icons/react'

  Since v2.1.8, new icons and the recommended way to import are suffixed with 'Icon' (e.g., `HeartIcon`). Older, non-suffixed names (e.g., `Heart`) are deprecated but still functional. The package was also renamed from `phosphor-react` to `@phosphor-icons/react` in v2.
• IconContext
  wrong:

  import { IconContext } from 'phosphor-react'

  correct:

  import { IconContext } from '@phosphor-icons/react'

  Used to provide default styling (color, size, weight, mirrored) to all Phosphor Icons within a React tree via `IconContext.Provider`.
• FishIcon
  wrong:

  import { FishIcon } from '@phosphor-icons/react'

  correct:

  import { FishIcon } from '@phosphor-icons/react/ssr'

  For use within React Server Components (RSC) or environments that don't support React Context (e.g., Next.js Server Components), import icons from the `/ssr` submodule. These SSR variants do not inherit styles from `IconContext`.

Quickstart

Demonstrates importing individual icons, using `IconContext.Provider` for global styling, and overriding props on specific icons.

import React from 'react';
import ReactDOM from 'react-dom/client';
import { IconContext, HorseIcon, HeartIcon, CubeIcon } from '@phosphor-icons/react';

const App = () => {
  return (
    <IconContext.Provider
      value={{
        color: 'limegreen',
        size: 32,
        weight: 'bold',
        mirrored: false,
      }}
    >
      <div style={{ padding: '20px', fontFamily: 'sans-serif' }}>
        <h1>My Awesome Icons</h1>
        <p>Icons inheriting context defaults:</p>
        <HorseIcon /> {/* Will be lime-green, 32px, and bold! */}
        <HeartIcon /> {/* Me too! */}
        <CubeIcon /> {/* Me three :) */}

        <p>Icons with overridden props:</p>
        <HeartIcon color="#AE2983" weight="fill" size={48} />
        <CubeIcon color="teal" weight="duotone" mirrored={true} />
      </div>
    </IconContext.Provider>
  );
};

const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
root.render(<App />);