Blade Iconic Icons Laravel Package

Getting Started

Install and render one icon before writing any abstraction.

composer require codeat3/blade-iconic-icons

Laravel package auto-discovery registers the service provider; for the happy path there is nothing to publish. Drop a component into any Blade view:

<x-iconic-home class="w-6 h-6 text-slate-600" />

The component name is the icon name with an iconic- prefix. Three entry points exist (all from the underlying Blade Icons layer) — pick one per context and stay consistent:

{{-- component: the default in views --}}
<x-iconic-home class="w-5 h-5" />

{{-- directive: useful inside larger markup strings --}}
@svg('iconic-home', 'w-5 h-5 text-blue-600')

{{-- helper: when you need the object itself --}}
{!! svg('iconic-home')->class('w-5 h-5')->toHtml() !!}

Discover what actually exists. The README is not the source of truth — the shipped SVGs are:

ls vendor/codeat3/blade-iconic-icons/resources/svg | sed 's/\.svg$//' | sort | column -c 120

Capture that output once; it doubles as the whitelist for any dynamic-name use later.

Set defaults globally instead of repeating classes. This is the highest-return first step — override only where a call site genuinely differs:

php artisan vendor:publish --tag=blade-icons

// config/blade-icons.php
'class' => 'w-5 h-5 shrink-0',
'attributes' => ['aria-hidden' => 'true', 'focusable' => 'false'],

First real use case is almost always a nav/sidebar or a toolbar of buttons — build one wrapper component, then place icons.

Implementation Patterns

One project-local wrapper. Everything below assumes a single <x-ui.icon> you own, so sizing, accessibility, and fallbacks live in one file:

{{-- resources/views/components/ui/icon.blade.php --}}
@props(['name', 'label' => null])
@php $svg = svg("iconic-{$name}"); @endphp

@if ($svg)
    {{ $svg->class('w-5 h-5 shrink-0')->attributes([
        'aria-hidden' => $label ? 'false' : 'true',
        'focusable'   => 'false',
    ])->toHtml() }}
@else
    <span class="inline-block w-5 h-5 rounded bg-red-200" title="missing icon: {{ $name }}"></span>
@endif

The @else branch is the most valuable line in the file: an unknown icon renders as empty output with no exception, so a typo or renamed glyph fails silently in production.

Drive dynamic names from config, never from request input.

// config/nav.php
['label' => 'Dashboard', 'route' => 'dashboard',     'icon' => 'home'],
['label' => 'Billing',   'route' => 'billing.index', 'icon' => 'credit-card'],

@foreach (config('nav') as $item)
    <a href="{{ route($item['route']) }}" class="flex items-center gap-2">
        <x-ui.icon :name="$item['icon']" />
        {{ $item['label'] }}
    </a>
@endforeach

If names must come from the database (CMS menus), validate against the globbed icon list cached at boot — never pass them through unchecked.

Hot loops. Parsing the SVG per render adds up in data tables and permission grids. Run php artisan icons:cache at deploy, or memoize the markup keyed on name + class string:

$html = Cache::rememberForever('icon:check:w-4', fn () =>
    svg('iconic-check')->class('w-4 h-4 text-emerald-600')->toHtml()
);

Flush that cache whenever the package version changes.

Tailwind safelisting. Dynamically composed classes (w-{{ $size }}) get purged. Keep a literal map in PHP and safelist it:

// config/icons.php
'sizes' => ['sm' => 'w-4 h-4', 'md' => 'w-5 h-5', 'lg' => 'w-6 h-6'],

Mail and notifications. Mail clients strip external CSS and often <svg> itself. Inline presentation as attributes rather than Tailwind classes, and pair every icon with text.

Livewire. Nothing special — icons render server-side on each component render. Prefer the component form so wire: attributes fall through to $attributes if you forward them.

Guard upgrades with a test. Icon names come from upstream, so a version bump can rename a glyph without warning:

public function test_required_icons_exist(): void
{
    foreach (['home', 'user', 'settings', 'trash'] as $icon) {
        $this->assertNotNull(svg("iconic-{$icon}"), "Missing Iconic icon: {$icon}");
    }
}

Gotchas and Tips

• Treat this as absorbed code, not a dependency. Last release May 2021, zero dependents, pinned to Iconic Icons v1.2.1, and its blade-icons constraint is ^1.0. If your app is on Blade Icons 2.x, Composer will conflict. The escape hatch is trivial — copy resources/svg into the app and register it yourself:

  BladeIcons::registerSet(resource_path('svg/iconic'), 'iconic');
  

  Budget for that fork path from day one.
• Cache ordering on deploy. With a cached manifest, new or replaced SVGs have no effect until cleared: icons:clear → icons:cache → view:clear.
• Never publish the icons. Published copies aren't refreshed by composer update — the classic "fine locally, blank in prod" incident. Serve from vendor/ so the package stays the single source.
• Unknown icons fail silently. No exception, just empty markup. Keep the wrapper's @else, and style the fallback loudly in dev so a missing glyph is impossible to miss.
• Duplicate SVG IDs. If a glyph carries id/clipPath/gradient defs and renders twice on one page, the second instance can lose its fill. Iconic is monochrome so this is usually moot — but check anything repeated in table rows or cards.
• Escaping. <x-iconic-* /> returns an HtmlString and is safe. If you hand-roll {!! svg($name)->toHtml() !!}, $name must never be user-controlled — that's an HTML injection point.
• Directive placement. @svg emits markup; it cannot be interpolated into an attribute (:class="@svg(...)" won't work) or spliced into an existing tag. Use the component when you need attribute merging.
• Debugging "icon renders empty", in order: (1) resolved package version and blade-icons major, (2) exact name/casing/hyphenation against resources/svg, (3) manifest cache — php artisan icons:clear, (4) compiled views — php artisan view:clear, (5) dd(svg('iconic-home')) to confirm the set is registered at all.
• Extension points. The attribute bag is the intended customization surface; Blade Icons' own config (class, attributes, fallback, component disabling) is the supported global override. Don't subclass the package's component — that couples you to internals of unmaintained code.
• Accessibility. Decorative icons need aria-hidden="true" + focusable="false"; meaningful ones need a <title> inside the SVG or adjacent visually-hidden text. Bake both into the wrapper so no call site can forget.
• Scope check. This is Blade-only, single-set, and static. If you need multiple icon families or an npm-driven pipeline, use blade-ui-kit/blade-icons directly (or the icon set's JS package) rather than layering a wrapper you'll outgrow.