Blade Carbon Icons Laravel Package

Getting Started

Install with Composer; the service provider is auto-discovered, so there is nothing to register, publish, or configure:

composer require codeat3/blade-carbon-icons

Pin the version explicitly (2.39.0 rather than ^2.0) — this is a single-maintainer commodity package, and an unpinned minor bump is the only realistic way it can surprise you.

Where to look first. The package ships no documentation of its own beyond the README; the authoritative source of truth is the upstream Carbon icon catalogue. The component tag is derived from the Carbon icon name, so the fastest way to discover what to type is to search the catalogue for the verb you want (e.g. "add", "arrow down", "user"), then mentally kebab-case it into <x-carbon-{name} />. Build a throwaway route that renders a sample of the icons you intend to use — this is your smoke test and your naming cheatsheet in one:

{{-- routes/web.php -> Route::view('/icons', 'icons.smoke'); --}}
<x-carbon-add />
<x-carbon-edit />
<x-carbon-trash-can />
<x-carbon-search />
<x-carbon-settings />

First real use case. Drop a single icon into an existing Blade view with Tailwind (or your utility classes) for size and color:

<button class="inline-flex items-center gap-2 rounded bg-blue-600 px-3 py-2 text-white">
    <x-carbon-add class="h-4 w-4" aria-hidden="true" />
    <span>New item</span>
</button>

Colors work via currentColor — pass a text-* class, not a fill-* — which is what you want for theming and dark mode. Size via h-* w-*. The component renders inline <svg>, so there is no build step and nothing to add to your asset pipeline.

If you have any Blade-rendered view in the app, this is a five-minute install. If you are Inertia/React/Vue across the board and never render Blade server-side, stop here — a JS icon package is the right answer.

Implementation Patterns

Standard usage. Treat each icon as an inline SVG primitive: pass class for utilities, aria-hidden="true" for decorative icons, and role="img" plus aria-label (or a nested <title>) for meaningful ones. Establish this convention on day one and write it down — without it, every feature team reinvents sizing and accessibility and you end up with inconsistent icons across a product.

Composing a house icon set. The single highest-value pattern is a thin wrapper per role rather than scattered <x-carbon-*> tags, so a future swap is a one-file edit:

{{-- resources/views/components/ui/icon.blade.php --}}
@props(['name', 'size' => 'md', 'label' => null])
@php
    $sizes = ['sm' => 'h-4 w-4', 'md' => 'h-5 w-5', 'lg' => 'h-6 w-6'];
    $classes = $sizes[$size] . ' shrink-0';
@endphp

@if ($label)
    <x-dynamic-component
        :component="'carbon-' . $name"
        class="{{ $classes }}"
        role="img"
        aria-label="{{ $label }}"
    />
@else
    <x-dynamic-component
        :component="'carbon-' . $name"
        class="{{ $classes }}"
        aria-hidden="true"
        focusable="false"
    />
@endif

Note the x-dynamic-component idiom — it is how you compose icons whose names are driven by data (e.g. a nav item's icon column). This is also the seam that lets you migrate to a sibling blade-* package later without touching every template.

Navigation and menus. Icons pair naturally with link / nav-link components. The pattern that scales is a single icon field on the model or config array, resolved through the wrapper above:

<nav class="space-y-1">
    @foreach ($items as $item)
        <a href="{{ $item['href'] }}" class="flex items-center gap-3 rounded px-3 py-2 hover:bg-gray-100">
            <x-ui.icon :name="$item['icon']" />
            <span>{{ $item['label'] }}</span>
        </a>
    @endforeach
</nav>

Livewire and admin panels. No special handling is required — inline SVG renders fine inside Livewire components. What does matter is view-cache cost on a cold deploy: the package registers a large component set, so measure the diff between a cold view:cache with and without the package if your app is icon-heavy. Use php artisan view:clear && php artisan view:cache in CI to make this a known number rather than a surprise.

Email and PDF. This is one of the few icon approaches that survives an email-template pipeline without external asset calls — inline SVG sits in the HTML with no CDN and no webfont. Verify against your mail client matrix; Gmail historically strips some SVG, so treat it as a progressive enhancement.

Gotchas and Tips

Icon names are not always the obvious word. Carbon uses separator-heavy names (arrow--down, add--alt, chevron--right) and the package's kebab-casing of those into Blade component names is the single most common source of "component not found" errors. When a tag fails, do not trust your intuition — open the Carbon catalogue, match the exact icon, and adapt its name. Build the smoke-test view above and keep it around; it is your fastest lookup.

class may not merge the way you expect. Blade components vary in whether they append the incoming class to internal defaults or replace it. If utilities like h-4 w-4 seem to have no effect while the icon renders, that is a merge problem, not a Tailwind purge problem — inspect the rendered SVG in devtools and, if necessary, style the component's wrapper or pass the classes through your own x-ui.icon wrapper where you control the merge.

Tailwind JIT and dynamic component names. Because <x-dynamic-component :component="'carbon-' . $name"> builds the tag at runtime, Tailwind's content scanner never sees the class strings you assemble dynamically. Keep every utility class literal in a template ($sizes = ['sm' => 'h-4 w-4', ...], not concatenated). This bites people who build classes with string interpolation and then wonder why the production build loses icons.

Accessibility defaults are not set for you. Inline SVGs are announced as images by screen readers unless you mark them. Adopt a rule: decorative → aria-hidden="true" focusable="false"; meaningful → role="img" + aria-label. Bake this into the wrapper component so no page can forget. This is also the convention a design review or an accessibility audit will ask for, so decide it once.

Do not run two icon packages side by side. Adding this alongside Heroicons, Blade UI Kit, or Font Awesome doubles your icon-governance surface for no gain and quietly splits your visual language. Pick one, document it, and migrate off the other fully in the same pilot — leaving legacy <i> tags around for "just a few" screens is how the swap stalls half-done.

Version and compatibility. 2.39.0 is the Laravel 13 line; 2.38.x is effectively the last line for older constraints. In a monorepo, one straggler on an older Laravel blocks a portfolio-wide bump — inventory your apps' laravel/framework and php constraints before you start, and pin a different line per app if needed. The release notes do not state the PHP floor implied by Laravel 13 support; check composer.json rather than assume.

Testing. Feature tests can assert on the SVG cheaply — $response->assertSee('<svg', false) is a weak check; prefer asserting on the aria-label you set for meaningful icons, or on the presence of a distinctive viewBox attribute. Wrap the assertion in a custom assertIcon() helper so a future package swap touches one method, not every test.

License split. The Composer package is MIT but the Carbon icon assets it vendored are Apache-2.0. If your organisation gates third-party assets through legal or procurement, confirm the attribution obligations for both before it reaches production — this is a review item, not a code item, but it is the one thing that can halt adoption after engineering signs off.

Exit plan. Keep it cheap: the wrapper component above isolates the icon tag to one file, the assets are plain SVGs, and the swap path is either vendoring the SVGs into resources/ or moving to another codeat3/blade-* package. A day's work at most. Do not add a second abstraction layer on top of the wrapper — that is how a commodity dependency becomes load-bearing infrastructure.