@phosphor-icons/react: Install, Weights, SSR and Icon Names

Install with npm install @phosphor-icons/react, then import icons with the Icon suffix: import { HeartIcon } from '@phosphor-icons/react'. Pick one of six styles with the weight prop (thin, light, regular, bold, fill, duotone). In a React Server Component, import from @phosphor-icons/react/ssr instead. Facts below are from the official @phosphor-icons/react README and the package source, version 2.1.10.

Install and first icon

npm install @phosphor-icons/react

import { HeartIcon, SparkleIcon, XIcon } from '@phosphor-icons/react';

export function Actions() {
  return (
    <>
      <HeartIcon size={24} weight="fill" color="#e11d48" />
      <SparkleIcon size={24} weight="duotone" />
      <XIcon size={20} aria-label="Close" />
    </>
  );
}

The package needs React 16.8 or newer (its peer dependency). Browse all icons on the Phosphor pack page.

Icon names and exports

Every icon has two exports in version 2.1.10. In the package's type file for Sparkle:

/** @deprecated Use SparkleIcon */
export declare const Sparkle: Icon;
export { I as SparkleIcon };

So SparkleIcon, QuestionIcon, XIcon and CoffeeIcon are the names to use. Old code with import { Sparkle } from '@phosphor-icons/react' still runs, but editors show it as deprecated. Names are the icon name in PascalCase plus Icon: arrow-right becomes ArrowRightIcon, bell-simple becomes BellSimpleIcon.

There are no per-weight exports. HeartFill, HeartThin or HeartDuotone do not exist; the weight is a prop.

The six weights

All weights share one 256x256 viewBox, so swapping weight never shifts layout. A common pattern is regular for inactive tabs and fill for the active tab:

<HouseIcon weight={active ? 'fill' : 'regular'} size={24} />

Duotone

The duotone weight draws a background shape with opacity="0.2" under the regular outline, both in the current color. There is no separate prop or CSS variable for the second color in the React package. For two real colors, use the duotone SVG from the pack page and set each layer's fill yourself; the duotone icon color guide shows how.

Props and IconContext

Props, from the package's IconProps type:

Any other SVG attribute (className, aria-hidden, onClick) passes through. Because the default size is 1em, icons follow the font size of their parent.

Set defaults for a subtree with IconContext:

import { IconContext, BellIcon, GearIcon } from '@phosphor-icons/react';

<IconContext.Provider value={{ size: 20, weight: 'bold', mirrored: false }}>
  <BellIcon />
  <GearIcon />
</IconContext.Provider>

Next.js and Server Components

The default entry uses React context, which Server Components do not support. The README's fix is the ssr entry:

// app/page.tsx (Server Component)
import { FishIcon } from '@phosphor-icons/react/ssr';

export default function Page() {
  return <FishIcon size={32} weight="duotone" />;
}

Icons from /ssr take props but do not inherit IconContext. In Client Components, keep using the main entry.

@phosphor-icons/react is not in Next.js's default optimizePackageImports list, so add it, as the README recommends:

// next.config.js
module.exports = {
  experimental: { optimizePackageImports: ['@phosphor-icons/react'] },
};

Without Next.js, you can import one icon module directly to speed up dev builds: import { BellSimpleIcon } from '@phosphor-icons/react/dist/csr/BellSimple'. Full Next.js icon setup: SVG icons in Next.js.

phosphor-react vs @phosphor-icons/react

phosphor-react (last version 1.4.1) is the original package. Its README says it has been replaced by @phosphor-icons/react and will not get new icons. To migrate:

1. npm uninstall phosphor-react && npm install @phosphor-icons/react
2. Change imports from 'phosphor-react' to '@phosphor-icons/react'.
3. Rename icons to the Icon suffix (Coffee to CoffeeIcon) to clear deprecation warnings.

Custom icons

The README shows how to add your own icon with all six weights: build a Map<IconWeight, ReactElement> with the inner SVG content of each weight, then render <IconBase weights={weights} {...props} />. For Server Components, render <SSRBase /> instead.

Other frameworks

For Vue setup, see SVG icons in Vue.

Phosphor vs Lucide

Phosphor has 1,512 icons in six weights; Lucide has about 1,890 icons in one stroke style that you tune with strokeWidth. Pick Phosphor when you need filled and outline versions of the same icon (active states, marketing pages). Pick Lucide for a larger single style. Side by side: Phosphor vs Lucide.

FAQ