Blade Simple Line Icons Laravel Package

Getting Started

Install and render one icon in under five minutes.

composer require codeat3/blade-simple-line-icons

There is no publish step, no config file, no migration, no asset build. Laravel's package auto-discovery registers the service provider, which in turn registers every SVG in the set with blade-ui-kit/blade-icons as an anonymous Blade component.

Resolve the component prefix empirically before you write anything else. The docs contradict themselves (<x-simple-line-icons-home /> vs <x-simple-line-icon-* />), and a wrong guess fails at render time, not at boot. Do this instead of trusting the README:

# 1. What does the provider actually register?
grep -rn "prefix\|->icons(\|set(" vendor/codeat3/blade-simple-line-icons/src/

# 2. What are the files actually named?
ls vendor/codeat3/blade-simple-line-icons/resources/svg | head -20

# 3. Then render it once in tinker
php artisan tinker
>>> Blade::render('<x-simple-line-icons-home />')

Whichever variant returns an <svg> is the one. Delete the other from your mental model, note it in the PR description, and move on.

First use case — a nav link in your layout. This is the canonical entry point: one icon, one template, no architecture decisions required.

<a href="{{ route('dashboard') }}" class="flex items-center gap-2 text-gray-700 hover:text-gray-900">
    <x-simple-line-icons-home class="w-5 h-5" />
    <span>Dashboard</span>
</a>

If that renders and sizes correctly, the integration is done. Everything after this is styling conventions and scope discipline.

Where to look first in the repo:

Implementation Patterns

Wrap it — do not scatter raw component tags

The single highest-leverage decision you make with this package is inserting one indirection layer. A thin <x-icon> wrapper costs 10 lines and buys you default sizing, a consistent accessibility policy, and — critically — a one-file swap point if you ever replace the package.

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

@php
    $component = "simple-line-icons-{$name}"; // adjust to your resolved prefix
@endphp

<x-dynamic-component
    :component="$component"
    {{ $attributes->class($size) }}
    aria-hidden="true"
    focusable="false"
/>

Usage becomes package-agnostic:

<x-icon name="home" />
<x-icon name="user" class="text-indigo-600 w-6 h-6" />

Now the ~190 x-simple-line-icons-* tags appear in exactly one file across the codebase. Migrating off the package is a find-and-replace on string literals, and you keep that exit cheap.

Drive dynamic icons from a config map, never from user input

Nav menus, notification types, and status badges all want "icon chosen by a key." Put the mapping in a config file so the component set stays a closed list:

// config/icons.php
return [
    'dashboard' => 'home',
    'settings'  => 'settings',
    'billing'   => 'credit-card',
    'members'   => 'people',
];

<x-icon :name="config('icons.' . $nav->key, 'question')" />

The ?: 'question' default matters: an unmapped or mistyped key produces a render-time Unable to locate a class or view for component exception, which is a 500 on a page, not a build failure.

Standardize on class-based sizing, not width/height attributes

Pass Tailwind (or your utility classes) through $attributes->class(). Icon components from blade-icons merge attributes onto the root <svg>, so classes land where you expect:

<x-icon name="bell" class="w-4 h-4" />        {{-- inline with 14px text --}}
<x-icon name="bell" class="w-8 h-8" />        {{-- empty-state hero --}}
<x-icon name="bell" class="w-5 h-5 text-amber-500" />

Inline icons need explicit dimensions. An <svg> with no sizing attribute and no class will happily expand to fill its container — which looks like a layout bug, not a missing prop.

Inline-with-text alignment

The most common day-to-day friction is vertical misalignment inside buttons and badges. The fix is flex items-center on the parent plus an explicit size on the icon — not vertical-align on the SVG:

<button class="inline-flex items-center gap-1.5 px-3 py-2 rounded-md">
    <x-icon name="plus" class="w-4 h-4" />
    New item
</button>

Livewire and Blade components

No special handling needed — the package is pure template output, so it composes with Livewire exactly like any other Blade partial. It survives Livewire re-renders, wire:loading swaps, and validation-error re-renders without state concerns. Just keep the <x-icon> wrapper available in the Livewire component's view, which it is by default.

Mail and PDF templates

Inline SVG support in email clients is unreliable (Outlook desktop and much of the Gmail webmail UI will drop it). Do not assume the package solves icons in mail. If you need icons in transactional email, generate PNGs from the same source SVGs and reference them, or accept text-only email. For PDFs (DomPDF, Browsershot), test explicitly — DomPDF's SVG support is partial.

Testing

One smoke test per icon package is the right amount of coverage, and it catches the only failure mode that matters (a renamed component):

it('renders an icon', function () {
    $html = Blade::render('<x-icon name="home" />');
    expect($html)->toContain('<svg');
});

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

The second test is the valuable one — it walks your config map and fails if an upstream rename or a bad key broke a page before a user finds it.

Gotchas and Tips

Color often does not "just work." Simple Line Icons were converted from an icon font, so the paths are fill-based rather than stroke-based. class="text-red-500" only applies if the paths inherit currentColor. Test one icon first:

<x-icon name="home" class="text-red-500 w-6 h-6" />

If the color doesn't change, either pass fill="currentColor" (works if the paths have no hardcoded fill attribute) or add a scoped CSS rule. If the source SVGs hardcode fill="#000", a fill="currentColor" attribute on the root will not override child paths — you'd need svg path { fill: currentColor; } (with !important inside Tailwind utilities) or a one-off script to strip hardcoded fills at vendor time. Confirm which situation you're in on day one, because it determines your entire theming story. The same logic applies inversely if any icons are stroke-based: stroke and stroke-width need to be set on the paths, not the root.

class default lives in Blade Icons config. vendor/blade-ui-kit/blade-icons/config/blade-icons.php sets a default class applied to every rendered SVG. If every icon on a page mysteriously gets w-6 h-6 or similar, that's where it comes from — not this package.

Clear the icon cache after composer update. Blade Icons caches SVG contents. If icons vanish or look stale after a dependency bump, run:

php artisan icons:clear

and, if you've cached in production, php artisan icons:cache as part of your deploy.

Accessibility is your job, not the package's. The component renders a bare <svg> with no aria-hidden and no title. Decorative icons (next to visible text) must be aria-hidden="true" and focusable="false" — bake both into your <x-icon> wrapper so they're never forgotten. Meaningful icons with no adjacent text need role="img" plus an aria-label, which you pass through attributes:

<x-icon name="warning" role="img" aria-label="Warning" class="w-5 h-5 text-red-600" />

You cannot easily inject a <title> child element through the component tag, so aria-label is the practical route.

Component name collisions across icon sets. If blade-tabler-icons, blade-unicons, or a sibling set is already installed, check the registered set prefixes in config/blade-icons.php (or vendor/blade-ui-kit/blade-icons/config/blade-icons.php) for overlap. Two sets claiming the same prefix silently shadow each other and you'll chase a "wrong icon" bug for an hour.

Autocomplete noise is real and permanent. Every icon in the set registers as a Blade component. Your IDE and x- autocomplete list will balloon by ~190 entries forever. This is the accepted cost of the inline-SVG approach; if it bothers the team, restrict usage to the <x-icon> wrapper and never reference raw tags in application code.

Missing icons throw at render, not at deploy. There is no compile-time validation of icon names. A typo produces Unable to locate a class or view for component [simple-line-icons-foo] — a 500 on a user-facing page. Your mitigation is the config-map test above, plus keeping dynamic names out of user-controlled input.

Upstream artwork is frozen — plan for it. Roughly 190 monochrome outline glyphs, no upstream momentum. If product asks for an icon that doesn't exist, the answer is "not from this set," not "file a ticket." Decide now whether missing icons are hand-drawn SVG partials in your own resources/views/components/, or a second icon source. The former is usually correct.

The full exit path is a rehearsal, not a theory. The SVGs are in vendor/codeat3/blade-simple-line-icons/resources/svg. Copying them to resources/svg/, pointing Blade Icons at your own directory, and dropping the dependency takes hours. Because the cost is hours, the correct posture is: pin ^1.6, stop thinking about it, and spend your attention on features.

Do not sweep the codebase. There is zero correctness pressure to migrate existing hand-rolled <svg> blocks to this package. Convert opportunistically, per template, when you're already editing that file. A repo-wide "standardize all icons" PR burns sprint capacity for no user-visible outcome and generates review fatigue — this is precisely the task that balloons beyond its value.

Pin ^1.6 and treat the Laravel 13 bump as a no-op. Release 1.6.0 is framework compatibility only — no API changes, no icon changes, no deprecations. It comes off your upgrade checklist without further review. Note it in the dependency register as low-criticality, replaceable, single-maintainer, and move on.

Know when you should not have installed this. If the app needs fewer than ~10 icons, copy those SVGs into resources/views/components/ as plain Blade partials — same result, one fewer dependency, zero supply-chain surface. That question is worth answering before the trial, not after.