Blade Prime Icons Laravel Package

Getting Started

Install

composer require codeat3/blade-prime-icons

That's it. No publish step, no assets to copy, no JS build changes, no migrations. Package auto-discovery registers a service provider that declares the PrimeIcons set to blade-ui-kit/blade-icons, so the SVGs are already in the vendor tree.

Verify what you got

composer show codeat3/blade-prime-icons
composer show blade-ui-kit/blade-icons   # the real engine — note the version

Then render one icon in an existing view to prove the wiring:

<x-prime-icons-check class="w-4 h-4" />

Where to look first

1. The package README — it lists the component prefix and the exact naming convention (whether <x-prime-icons-check /> maps to pi-check, or the pi- prefix is retained).
2. The blade-ui-kit/blade-icons docs, not this package's. Every behaviour you'll actually depend on — attribute merging, the svg() helper, the cache commands, fallback — lives there. This package is a data set; blade-icons is the runtime.
3. vendor/codeat3/blade-prime-icons/ — the set definition file is tiny and worth reading once to confirm the prefix and any default attributes.

First real use case

Replace a hand-rolled <i class="pi pi-user"></i> in a nav or admin layout with the component equivalent. Confirm visual parity side by side before doing a second one — the glyph geometry is identical, but sizing now comes from CSS classes on the <svg> rather than an icon-font font-size, so widths often shift by a pixel or two.

Implementation Patterns

Sizing and colouring — pass it all as attributes

<x-prime-icons-user class="w-5 h-5 text-slate-500" />
<x-prime-icons-check class="h-4 w-4 text-emerald-600" />

Attributes land on the root <svg>, so Tailwind utilities, style, width, height, and any data-* / wire:* attributes all pass straight through. Colour follows currentColor, so text-* classes are the idiomatic approach — don't reach for fill=.

Dynamic icon names (menus, model-driven icons)

<x-dynamic-component
    :component="'prime-icons-' . $item->icon"
    class="w-5 h-5"
/>

Store the bare name (check, user, chart-bar) in the database and concatenate at render. Pair this with the fallback config below so a bad row doesn't 500 the page.

The svg() helper and @svg directive

Inherited from blade-icons, useful when you need an icon inside a PHP expression or a helper method rather than a tag:

{{ svg('prime-icons-check', 'w-4 h-4 text-green-600') }}

I stick to the component syntax in views and reserve the helper for places that build markup strings (table cell renderers, notification builders, mailables).

Wrap it once for your design system

Don't sprinkle raw component tags across 60 files. Define one component with your defaults and let the team use that:

{{-- resources/views/components/icon.blade.php --}}
@props(['name', 'size' => 'w-5 h-5'])

<x-dynamic-component
    :component="'prime-icons-' . $name"
    {{ $attributes->merge(['class' => $size, 'aria-hidden' => 'true']) }}
/>

Then <x-icon name="check" class="text-red-500" /> everywhere. When you later swap icon sets or move to a different pack, there is exactly one file to change — this is the difference between a two-hour migration and a two-week one.

Cache at build time, not at runtime

php artisan icons:cache

Add this to your deploy pipeline as an explicit step after composer install. Without it, the first request on every cold container pays for scanning the SVG directory. Run php artisan icons:clear after any package upgrade before re-caching, or you'll serve stale glyphs.

Livewire

Works with no special handling — the component is inline SVG, so it survives DOM diffing and wire:loading swaps. Two practical notes: keep wire:* attributes on the component tag (they're merged onto the <svg>, and Livewire binds to the root element fine), and be aware that a wire:model.live field that re-renders a table of 500 rows also re-inlines 500 SVGs on each keystroke.

Testing

$this->get('/dashboard')
    ->assertSee('<svg', false)
    ->assertSee('prime-icons');

For component-level tests, render <x-prime-icons-check /> and assert the viewData/output contains an <svg> rather than asserting exact path data — path data changes on upstream bumps and brittle assertions there are pure noise.

Gotchas and Tips

The pi- prefix usually disappears from the component name. PrimeIcons calls it pi-check; the Blade component is almost certainly <x-prime-icons-check />. Getting this wrong produces a "component not found" error rather than a missing icon, which is at least a loud failure — but confirm it in the README before you build conventions on top of a guess.

Pin the version and treat upgrades as reviewable changes. This package does not version-track PrimeIcons upstream, so icon names and glyphs can move under a minor bump. Icon renames upstream are the only realistic breakage vector: they fail silently in some paths (a blank <svg>) and loudly in others. Pin ^1.8 and read the diff on bumps rather than auto-merging.

Check the blade-icons constraint on day one if you run other icon packs. Every codeat3/blade-* package sits on blade-ui-kit/blade-icons. If you already have Heroicons or another set installed, a constraint shift in a new release can produce a Composer resolution conflict across all of them at once. Resolve the full graph in a scratch branch before you commit to the upgrade.

Attributes merge, they don't replace. class is additive against any set-level default. If an icon comes out the wrong size and you're sure your class is right, dump the rendered HTML — you're probably fighting a default class or width/height attribute from the set definition, not a CSS specificity problem.

Colour is currentColor; fill and stroke will fight you. PrimeIcons are solid-fill SVGs. Setting stroke="currentColor" or overriding fill produces either invisible icons or double-drawn shapes. Use text-* and leave the fill alone. If an icon renders black in a dark theme, the cause is a missing text-* inheriting from a container, not the package.

Accessibility is on you. These render decorative by default only if you add the attribute. Decorative: aria-hidden="true". Meaningful (icon-only button): role="img" plus aria-label, or wrap in a <button aria-label="…"> and hide the icon.

Inline SVG is stripped by Gmail. If you use this in mailables, the icons will not appear in a large share of inboxes. Keep the font/CSS fallback for email, or pre-render PNGs — don't assume Blade parity extends to the inbox.

Dynamic names from the database need a fallback. blade-icons supports a fallback entry in its config so an unknown icon renders something instead of throwing. Enable it the same day you start storing icon names in a column; a single typo in a CMS field otherwise 500s the page.

Debugging checklist, in order:

1. php artisan icons:clear && php artisan icons:cache — solves most "it worked in staging" reports after an upgrade.
2. Confirm the component name against the set (prefix mapping).
3. grep the rendered HTML for the <svg> — if it's there but invisible, it's a sizing/colour/fill issue, not a package issue.
4. composer show blade-ui-kit/blade-icons — if you recently added another icon pack, suspect a set-registration collision before anything else.

Watch your payload on dense screens. Every icon is inlined per render. A sidebar with 40 icons is fine; an icon picker rendering 200+ distinct glyphs, or a data table where every row carries three icons, will visibly bloat HTML. Audit before someone builds a picker on top of this, and prefer a small curated subset in hot lists.

Maintenance watch duty is the real cost. Roughly an hour a quarter: track blade-icons majors, Laravel majors, and PrimeIcons upstream. Assign it to whoever owns frontend assets. Unowned, this dependency resurfaces as a surprise during a framework upgrade — which is exactly what release 1.8.0 (Laravel 13 compatibility, no API changes) exists to prevent.