Blade Unicons Laravel Package

Getting Started

Install and render in under five minutes.

composer require codeat3/blade-unicons

Package discovery registers the service provider automatically — no asset publishing, no npm, no build step. Drop a component into any Blade view and you get inline SVG:

<x-unicons-home class="h-5 w-5 text-slate-500" />

Rendering goes through blade-ui-kit/blade-icons, so the component name maps directly to a filename.

Where to look first, in order:

1. vendor/codeat3/blade-unicons/resources/svg/ — the authoritative icon inventory. unicons-home.svg → <x-unicons-home />. Grep this directory (ls | grep -i arrow) instead of browsing the Unicons marketing site, which lists icons the package may not ship or names differently. Bookmark this path; you will use it daily.
2. vendor/codeat3/blade-unicons/composer.json — check the pinned blade-icons constraint (^1.0 vs ^2.0) and the PHP/Laravel floor. This tells you more about real compatibility than the changelog.
3. config/blade-unicons.php after php artisan vendor:publish --tag=blade-unicons-config — prefix and path overrides. Most teams never touch it.

First use case: pick one layout partial — sidebar nav, topbar, or a card component — and replace 5–10 <i class="fa-..."> tags or hand-pasted SVG partials. Small enough to verify visually, large enough to prove the workflow.

Before the second use case, build the wrapper:

{{-- resources/views/components/icon.blade.php --}}
@props(['name'])

<x-dynamic-component
    :component="'unicons-' . $name"
    {{ $attributes->class(['shrink-0']) }}
/>

Every view then calls <x-icon name="home" class="h-5 w-5" /> and no view ever references the vendor component directly. This costs an hour and is the entire abandonment mitigation — if the package dies, you rewrite one file and vendor the SVGs.

Implementation Patterns

Sizing and colour. Icons inherit currentColor, so colour comes free from text colour (text-red-500, dark-mode variants, CSS variables). Size with utilities on the wrapper: h-4 w-4 inline with text, h-5 w-5 for nav, h-6 w-6 for feature cards. Do not mix width/height attributes with classes — pick one.

Alias vendor names behind a project vocabulary. The highest-leverage day-to-day pattern is an alias map, so designers and copywriters say pencil and no view hardcodes a vendor name:

// config/icons.php
return [
    'edit'     => 'edit',
    'delete'   => 'trash-alt',
    'settings' => 'setting',
    'search'   => 'search',
];

<x-icon :name="config('icons.delete')" class="h-4 w-4" />

{{-- DB/CMS-driven names, with a fallback --}}
@php($icon = config('icons.' . $row->icon, 'question-circle'))
<x-icon :name="$icon" />

A vendor rename or a provider swap becomes a one-file diff, and you end up with an enumerated list of the icons you actually use.

Style variants. Unicons ships line, solid, monochrome, and thinline. Filenames are flattened across style directories, so check the vendor directory to see how variants are distinguished (a -solid suffix, or separate names) before assuming both <x-unicons-heart /> and <x-unicons-heart-solid /> exist. Line and thinline are stroke-based; solid and monochrome are fill-based. Both respond to currentColor, but stroke-based icons cannot be meaningfully bolded via stroke-width from a class unless the SVG hardcodes it — pick the right style up front, do not fight it.

Dynamic names are the norm, not the exception. Table rows, DB-rendered menus, and permission-driven action buttons all route through the <x-icon> wrapper's x-dynamic-component. Never build component tag strings in PHP — pass a name and let the wrapper resolve it.

Attribute passthrough. Attributes land on the <svg>, so tooltips and JS hooks work:

<x-icon name="info" class="h-4 w-4"
         x-tooltip="Billable hours only"
         data-testid="billing-info" />

Split decorative vs. meaningful icons. Default aria-hidden="true" in the wrapper and require an explicit $label prop to opt out — it makes the correct choice the default:

{{-- decorative --}}
<x-icon name="search" class="h-4 w-4" aria-hidden="true" />

{{-- meaningful: requires a label to override the default --}}
<x-icon name="warning" label="Requires attention" class="h-5 w-5 text-amber-500" />

Test the icon surface in CI. The realistic failure mode with a low-adoption package is an upstream rename that silently blanks one page. Turn it into a red test:

it('renders every aliased icon', function () {
    foreach (array_unique(array_values(config('icons'))) as $name) {
        $html = Blade::render("<x-icon name=\"{$name}\" />");
        expect($html)->toContain('<svg');
    }
});

Cheap, and it catches a swapped icon set, a typo'd alias, or a namespace regression after an upgrade.

Where it fits well: admin panels, Livewire views, Filament-adjacent custom pages, server-rendered marketing pages, PDF/export templates. Where it does not: Inertia/Vue/React front ends (import Unicons from npm directly) and HTML email (see gotchas).

Gotchas and Tips

icons:cache belongs in the build, not the boot. php artisan icons:cache writes a manifest that removes per-request filesystem lookups — a real win on icon-dense pages. But it writes to disk, so running it in a boot script on a read-only filesystem (common in containerized/immutable deploys) throws. Put it in the Dockerfile after composer install, and run php artisan icons:clear first if you cache config and routes in the same layer.

Re-cache after any dependency change. A composer update that alters the icon inventory requires re-running icons:cache, or new icons silently render nothing. Wire it into the build pipeline, not into a human's checklist.

Emails strip inline SVG. The "icons render where fonts fail" pitch is true for PDFs and server-rendered HTML, but Gmail, Outlook, and most clients strip <svg> entirely. For mail templates render PNGs or use a bulletproof CSS background image — do not point <x-icon> at resources/views/emails/.

Payload adds up on icon-dense pages. Each icon duplicates inline markup. A 40-row table with two icons per row ships a lot of uncacheable <path> data. Measure the delta on a representative page. If it is material, the escape hatch is a sprite: extract a <symbol> sheet from the vendor SVGs and use <use href="#...">, keeping the same <x-icon> API so no views change.

Typo'd component names fail loudly; aliases fail silently. <x-unicons-hoem /> throws component-not-found, which is good. A wrong key in config/icons.php renders nothing or a fallback — which is exactly why the CI test above earns its keep.

Two stars, zero dependents — you are the first to hit any bug. Pin exactly ("codeat3/blade-unicons": "1.10.*"), keep the wrapper, and document the exit in the README: vendor the SVGs and register them yourself, or move to blade-ui-kit/blade-icons with Unicons as a custom set.

Read composer.json, not the changelog. 1.10.0 is a Laravel 13 compatibility bump — a good maintenance signal, but it says nothing about blade-icons v1 vs v2. If this package is stuck on v1 while another icon package pulls v2, you get a dependency conflict at the worst possible moment.

Sanitization is a non-issue today and a stored-XSS vector tomorrow. The bundled SVGs are trusted vendor files. It becomes a problem the moment someone points the icon path at user-uploaded SVGs. Keep the path vendor-controlled.

Small-size legibility. Line and thinline styles look thin below ~16px and can disappear against light backgrounds at h-3 w-3. Below 16px, prefer solid.

Name collisions are avoided by prefix; vendor bloat is not. x-unicons-* will not collide with x-heroicons-*, so coexisting sets are technically fine — but do not accumulate them. Every blade-* set adds vendor weight and a shared blade-icons dependency to reason about. Standardize on one.

Licensing is not the package's to solve. The wrapper does not change Iconscout's Unicons terms. Attribution, redistribution, and commercial use need clearing before a customer-facing rollout — check before production, not after.