Phosphor Icons

Rule: Don't mix weights randomly. Use one weight for a given UI region (e.g., all sidebar icons bold, all form hints light). Fill weight works well for active/selected states alongside regular for inactive.

React Usage

Basic Import

import { HouseIcon, GearIcon, BellIcon } from "@phosphor-icons/react";

<HouseIcon size={24} />
<GearIcon size={24} weight="bold" />
<BellIcon size={24} color="var(--muted-foreground)" />

Naming Convention

All icons are PascalCase + Icon suffix:

• House → HouseIcon
• Gear Six → GearSixIcon
• Arrow Right → ArrowRightIcon
• Chat Circle Dots → ChatCircleDotsIcon

When unsure of the exact name, check https://phosphoricons.com and search.

Props

interface IconProps extends SVGAttributes<SVGSVGElement> {
  color?: string;           // Any CSS color or "currentColor" (default)
  size?: number | string;   // px, em, rem, % — default 16
  weight?: "thin" | "light" | "regular" | "bold" | "fill" | "duotone";
  mirrored?: boolean;       // Flip for RTL
  alt?: string;             // Accessible label
}

Icons inherit color from parent text color via currentColor by default — usually you don't need to set color explicitly.

IconContext Provider

Set defaults for all icons in a subtree:

import { IconContext, HouseIcon, GearIcon } from "@phosphor-icons/react";

<IconContext.Provider value={{ size: 20, weight: "bold", color: "currentColor" }}>
  <HouseIcon />  {/* 20px, bold */}
  <GearIcon />   {/* 20px, bold */}
</IconContext.Provider>

Not available in Server Components — use explicit props there.

Server Components / SSR

Import from /ssr submodule:

import { HouseIcon } from "@phosphor-icons/react/ssr";

export default function Nav() {
  return <HouseIcon weight="bold" size={20} />;
}

SSR variants don't use React Context — pass all props explicitly.

Next.js Optimization

Add to next.config.js to avoid bundling all 9,000+ icon modules:

module.exports = {
  experimental: {
    optimizePackageImports: ["@phosphor-icons/react"],
  },
};

Without this, dev server startup and HMR are noticeably slower.

Direct Path Import (Alternative)

For environments without optimizePackageImports:

import { BellSimpleIcon } from "@phosphor-icons/react/dist/csr/BellSimple";

Vanilla HTML (Web Package)

CDN — Single Weight

Load only the weight you need:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/[email protected]/src/regular/style.css" />

<i class="ph ph-house"></i>
<i class="ph ph-gear"></i>

CDN — Multiple Weights

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/[email protected]/src/regular/style.css" />
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@phosphor-icons/[email protected]/src/bold/style.css" />

<i class="ph ph-house"></i>           <!-- regular -->
<i class="ph-bold ph-heart"></i>       <!-- bold -->

CSS Styling

Icons respond to font-size and color:

.nav-icon { font-size: 20px; color: #666; }
.nav-icon:hover { color: #000; }

Do NOT override font-family, font-style, font-weight, font-variant, or text-transform — these break icon rendering.

Icon Class Convention

All icons are lowercase kebab-case: ph-house, ph-gear-six, ph-arrow-right, ph-chat-circle-dots.

Common Icon Picks

Quick reference for frequent UI patterns:

For brand logos (GitHub, Stripe, Vercel, etc.), use svgl.app instead — see the svgl skill. Phosphor is for UI icons, svgl is for brand logos.

Sizing Guide

Duotone Tips

Duotone renders a two-tone version with one layer at 20% opacity. It's the most visually rich weight — use it for feature showcases, onboarding, and marketing sections.

In React, the secondary layer inherits the icon's color at reduced opacity. You can target layers via CSS if needed:

/* Target the background layer of duotone icons */
.ph-duotone::before { opacity: 0.15; }

Rules

1. One weight per region. Don't mix regular and bold in the same nav. Use fill for active states alongside regular for inactive — that's the only acceptable mix.

2. Prefer currentColor. Don't set explicit colors unless the icon needs to differ from surrounding text. Icons that inherit color stay consistent with theme changes.

3. Always add alt or aria-label for icons that convey meaning without adjacent text. Decorative icons next to labels can use aria-hidden="true".

4. Use optimizePackageImports in Next.js. Without it, dev startup is painfully slow.

5. SSR = /ssr import. Server Components cannot use IconContext.

6. Brand logos go through svgl.app, not Phosphor. Phosphor is for UI iconography.