Blade Icons Packages Collection Laravel Package

Getting Started

First, determine what you actually installed. codeat3/blade-icons-packages-collection is described as a curated list of blade-icons packages, not a rendering engine. Before you plan anything, spend five minutes answering one question: is this a Composer metapackage that pulls in icon sets, or is it documentation plus a config stub?

composer show codeat3/blade-icons-packages-collection   # requires? version constraints?
ls vendor/codeat3/blade-icons-packages-collection       # README vs. composer.json with require entries

• If require is empty or near-empty, you have a catalogue. Nothing renders yet — you still need to composer require the individual sets you want. Treat the package as shopping advice.
• If it declares blade-icons-* dependencies, you have a metapackage. Auto-discovery registers the sets and you can start rendering immediately — but read the Gotchas section before you build on it.

Install the substrate. The renderer is upstream and well maintained. If it is not already there:

composer require blade-ui-kit/blade-icons
php artisan vendor:publish --tag=blade-icons   # config/blade-icons.php

Confirm the version floor matches your PHP/Laravel: blade-icons v1.x supports older stacks; v2.x expects PHP 8.1+/Laravel 9+. Run composer why-not blade-ui-kit/blade-icons in a throwaway branch before committing.

Look at config/blade-icons.php first, then the package's README manifest. That config is where prefixes, default classes, and the components toggle live — it is the file you will edit most.

First use case: a "Built with" / integrations strip. This is the canonical job for brand iconography: a row of technology logos on a landing page, pricing grid, or docs header. Start with three or four icons, not forty:

<div class="flex items-center gap-6">
    <x-icon-laravel class="h-8 w-auto" aria-hidden="true" />
    <x-icon-php     class="h-8 w-auto" aria-hidden="true" />
    <x-icon-mysql   class="h-8 w-auto" aria-hidden="true" />
</div>

If that renders, the mechanical part of adoption is done. Everything after this is governance and consistency, not plumbing.

Implementation Patterns

Prefix every set, deliberately. blade-icons registers each set behind a prefix, and the prefix is what generates the component name (x-{prefix}-{icon}). The default prefixes from individual icon packages (heroicon, tabler, phosphor) are fine, but generic logo sets can collide on x-logo-laravel-style names. Decide the convention on day one and write it in docs/icons.md:

// config/blade-icons.php
'sets' => [
    [
        'path' => 'vendor/codeat3/.../resources/svg',
        'prefix' => 'brand',
    ],
],

Then every template uses x-brand-* consistently and a future second logo pack cannot silently shadow it.

Data-drive the grid, don't hand-write forty tags. Marketing pages change; arrays are cheaper to diff in review than markup.

@php
    $stack = [
        ['icon' => 'laravel',  'label' => 'Laravel'],
        ['icon' => 'php',      'label' => 'PHP'],
        ['icon' => 'postgres', 'label' => 'PostgreSQL'],
    ];
@endphp

<ul class="grid grid-cols-2 gap-4 sm:grid-cols-4">
    @foreach ($stack as $item)
        <li class="flex flex-col items-center gap-2">
            <x-dynamic-component :component="'brand-'.$item['icon']" class="h-10 w-auto" aria-hidden="true" />
            <span class="text-sm text-gray-600">{{ $item['label'] }}</span>
        </li>
    @endforeach
</ul>

x-dynamic-component keeps the loop honest and will throw loudly if a slug is wrong — which is what you want in CI.

Style with attributes, never edit the SVG. Icons render inline, so Tailwind utility classes land directly on the <svg>: class="h-6 w-6 text-slate-500". If you want a house default, set it once in config rather than repeating it in every template:

'class' => 'h-5 w-5',
'attributes' => ['aria-hidden' => 'true'],

Accessibility is your job, not the package's. Decorative logos get aria-hidden="true". Meaningful ones (a link to a partner, a status badge) need a label:

<x-brand-github class="h-5 w-5" aria-hidden="true" />
<span class="sr-only">GitHub</span>

Or pass aria-label when the icon stands alone as the accessible name. Do not rely on the SVG's <title>.

Vendor the SVGs you depend on. If the icons are public-facing, copy the ones you ship into your own resources/svg/ set (or a resources/svg/brand/ directory registered as a set) and commit them. This is the difference between a stable surface and one that changes because someone ran vendor:publish on an upgrade. It also makes the docs/icons.md register real: every file in the directory is a logo you have consciously chosen to ship.

Cache in the deploy pipeline, not on the fly. Icons are resolved and inlined from disk; caching makes repeated renders cheap:

php artisan icons:clear
php artisan icons:cache

Put those in the deploy script after composer install and before view:cache. This is also the fix for "the icon works locally but 404s in production."

Use @svg() for one-offs inside strings or non-component contexts. The directive is the escape hatch when a component tag doesn't fit:

@svg('brand-laravel', 'h-4 w-4 inline-block')

Livewire and Inertia need nothing special — the components are compiled Blade, so they hydrate as static markup with no runtime JavaScript and no client-side payload.

Write the register. A short docs/icons.md listing which logos you ship, why, which set they came from, and their source URL. It costs twenty minutes now and is the first thing you reach for when legal asks, when a brand refreshes, or when the next developer wonders why brand-vue exists but not brand-angular.

Gotchas and Tips

The catalogue-vs-component trap is the big one. Teams install this expecting <x-icon-apple /> to appear and find a list of packages. Name the distinction in the ticket before anyone estimates a sprint on it.

Name collisions fail silently. If two registered sets expose the same slug, you get one icon and no warning. Before adding a set, grep your templates for the prefixes involved:

grep -rn "x-brand-\|x-logo-" resources/views | sort | uniq -c | sort -rn | head

Then assert resolution in a test so a future set addition can't shadow an existing name:

test('brand icons in templates resolve', function () {
    expect(Blade::render('<x-brand-github />'))->toContain('<svg');
});

Stale icon cache is the most common production incident. New icon deployed, page shows a blank or a 404, local is fine. php artisan icons:clear && php artisan icons:cache and re-verify. Make it part of the deploy checklist, not tribal knowledge.

vendor:publish can clobber your edits. If you published SVGs into resources/svg/ and then customised them, a re-publish on upgrade may overwrite. Customisations belong in a separate registered set directory that you own — never in published vendor paths.

Pin the version, hard. Two stars and zero dependents means no crowd-sourced bug discovery; you are the first to hit breakage. Use an exact constraint ("1.2.3", not "^1.0") and note why in the commit message. Keep it out of any dependency path that gates a Laravel or PHP upgrade — a floating icon-pack requirement can deadlock composer update on a curator's release schedule.

Watch the build cost, not the request cost. Inlining is free at runtime; the cost is vendor/ size, container image size, autoloader classmap, and php artisan view:cache wall time. Measure before and after in a spike branch. "Install every set" is the anti-pattern — register what the design system actually consumes.

Slugs rename across majors. A set bump can quietly break every template using a renamed icon. The resolution test above catches this at CI time; add it to the suite before you add the second icon pack, not after.

Check licensing per set, not per repo. The MIT licence covers the code, not the marks. Bundled brand logos carry their own trademark and usage terms, and bundling obscures provenance. For a public marketing site, get a brand/legal review of the specific logos you render, and record the outcome in docs/icons.md so a takedown request has a documented response path.

This is not a UI icon set. Brand/logo iconography does not give you chevron-down, x-mark, or trash. Pair it with Heroicons, Phosphor, Tabler, or Lucide for interface icons and keep the two vocabularies separate in your head — x-brand-* for logos, x-heroicon-* for UI.

Debugging render issues, in order: (1) is the set actually registered — dump config('blade-icons.sets'); (2) does the component name match the prefix plus the file slug exactly, case-sensitively; (3) is the icon cache stale; (4) is another set shadowing the name. Ninety percent of "it doesn't render" lands in step 1 or 2.

Extension point when you need a missing logo: don't hack the vendor directory. Add the SVG to your own registered set under your own prefix, commit it with a source note, and link the provenance in docs/icons.md. That keeps upstream upgrades clean and makes the asset auditable.