Phosphoricons Laravel Package

Getting Started

Install and confirm the constraint first. composer require wireui/phosphoricons — on Laravel 13 you must be on ^2.5.0, since v2.5.0 is the release that added Laravel 13 support. Nothing else to register: the package ships a service provider that is auto-discovered and registers every icon as a Blade component.

Where to look first.

1. The Phosphor gallery (phosphoricons.com) for the icon names — those names are what map to component names, not the Heroicon names you may have memorised.
2. vendor/wireui/phosphoricons/ to see exactly which components were registered for your installed version — this is the fastest way to settle naming and attribute questions, and it beats guessing from the README of a different major.
3. Your config/phosphoricons.php after php artisan vendor:publish --tag=phosphoricons-config if you want a project-wide default weight.

First use case. Drop it into a layout the same day you install it — replace a hand-rolled SVG in a nav or button:

<x-phosphor-house class="size-5 text-zinc-500" />

Sizing is plain CSS/Tailwind (size-5, w-6 h-6), colour is inherited via currentColor, so <button class="text-white"> needs no extra icon styling. That single swap is the whole adoption story: icons become markup, not asset files, and there's no sprite, no @svg directive, and no build-step dependency.

Implementation Patterns

Weights/variants are an attribute, not a different icon. Phosphor ships six weights (thin, light, regular, bold, fill, duotone). Keep the weight at the call site when it's contextual (a filled star in a rating, an outline star in a list) and set the default in config when it's a house style:

<x-phosphor-star variant="fill" class="size-4 text-amber-400" />
<x-phosphor-bell variant="bold" class="size-5" />

Wrap it once, use it everywhere. The highest-leverage pattern in a real codebase is a thin local component (resources/views/components/icon.blade.php) that takes a semantic name and delegates, so swapping icon sets later is a one-file change:

{{-- <x-icon name="trash" /> --}}
<x-dynamic-component :component="'phosphor-' . $name" {{ $attributes }} />

Back that with an allow-list (enum or config array) rather than passing arbitrary user input into x-dynamic-component — you want a broken icon name to fail loudly in development, not render an empty component.

Buttons, empty states, and loading. The common production patterns:

• Action buttons: icon + label in a flex row, class="size-4 shrink-0" so the icon never squashes when the label wraps.
• wire:loading / form submit states: render both icons and toggle with wire:loading/wire:loading.remove — cheaper and less flickery than swapping the component server-side.
• Empty states and @forelse fallbacks: a large variant="duotone" icon at size-10 reads better than a heroicon here; duotone uses opacity on the secondary shape and picks up currentColor correctly.

Deployment and view caching. These are Blade components, so the compiled component map matters. On deploy, run php artisan view:cache as part of your normal pipeline — with a package that registers hundreds of components, an uncached first render is measurably slower. Always follow an upgrade with php artisan view:clear before view:cache.

Gotchas and Tips

• v2.5.0 is additive. It adds Laravel 13 support (first contribution from @novislab) with no breaking changes, no deprecations, and no API changes. The only action item is the composer constraint: if you're bumping an app to Laravel 13, bump Phosphor to ^2.5 in the same PR or composer update will hold you back on the older, Laravel-13-incompatible release.
• Names are Phosphor's, not Heroicons'. house not home, magnifying-glass not search, and there are numbered/weighted variants (arrow-fat-right, arrows-clockwise). Grep vendor/wireui/phosphoricons/ for the exact set supported by the version you have installed — component registration has changed shape across majors, and so has the attribute used to select a weight.
• Accessibility is opt-in. Decorative icons should be inert; standalone icon buttons need a label. Prefer putting the label on the button rather than the SVG (aria-label on the <button>, aria-hidden on the icon) unless you're certain of the component's default.
• Don't assume SVG works in every output channel. Inline SVG is fine in browsers and most modern mail clients, but dompdf and several PDF pipelines handle it poorly — for invoices and PDF exports, render a PNG or use a font-based approach instead.
• Icon count ≠ free. Inline SVG duplicates markup on every occurrence; a table with an icon per row is real bytes. Where the same icon repeats dozens of times in one view, define it once as a <symbol> and <use> it, or accept the weight and keep icons small.
• $attributes merging is your friend. Extra attributes (including class) pass through and merge with the component's defaults, which is how you get Tailwind overrides without forking the view — but specificity still wins, so avoid stacking conflicting width utilities.
• Extension points, in order of preference: (1) the config default weight, (2) your own wrapper component, (3) vendor:publish the views and edit them. Option 3 is the one that will cost you on the next upgrade — use it only for something you genuinely cannot wrap.
• One upgrade habit. Pin the package with a caret ("wireui/phosphoricons": "^2.5"), read the diff when the minor bumps, and run view:clear after every composer update. This package's failure mode is silent — a stale compiled component map renders nothing rather than erroring.