khatabwedaa/blade-css-icons
Blade CSS Icons renders icons in your Blade views without SVG files—just drop in the component and go. Clean, lightweight markup that inherits your text color and size, perfect for keeping Laravel UIs fast and simple.
Install
composer require khatabwedaa/blade-css-icons
There is no npm step, no asset publishing, and no Vite integration required. The icons are shipped as inline SVG Blade (anonymous) components, so the package works the moment Composer's autoloader is rebuilt. Commit composer.lock; there is nothing else to install.
Where to look first
The service provider — this is the single source of truth for the component prefix:
grep -R "anonymousComponent\|componentNamespace\|Blade::" \
vendor/khatabwedaa/blade-css-icons/src
Confirm the prefix once (x-css-gg-… in most setups) before you write it into hundreds of views. If the package exposes a config file, publish it with php artisan vendor:publish --provider="KhatabWedaa\BladeCssIcons\BladeCssIconsServiceProvider" and check whether the prefix is configurable.
The component directory — one file per icon, and the filename is the component name:
ls vendor/khatabwedaa/blade-css-icons/resources/views/components | head -50
This directory, not the CSS.gg marketing site, is the authoritative icon inventory. Names occasionally diverge from the website.
One icon file, read end-to-end. It is a few lines of <svg>; confirm whether it spreads {{ $attributes }} on the root <svg> element. That single detail determines whether class="h-5 w-5" works or silently does nothing.
First use case
An icon inside an existing button, sized and colored by Tailwind:
<button
type="button"
class="inline-flex items-center gap-2 rounded-md bg-indigo-600 px-3 py-2
text-sm font-medium text-white hover:bg-indigo-500"
>
<x-css-gg-add class="h-4 w-4" aria-hidden="true" />
New project
</button>
Because the SVGs are inline, they inherit currentColor — set the color with a text-* utility on the icon or the parent, never with fill unless you deliberately want to override the icon's paths. Verify with php artisan view:cache in staging so a broken compiled view fails before production.
Standardize sizes with a thin wrapper
Do not repeat class="h-5 w-5" at every call site. Wrap the package once and use a dynamic component for the icon name:
{{-- resources/views/components/app-icon.blade.php --}}
@props(['name', 'size' => 'h-5 w-5'])
<x-dynamic-component
:component="'css-gg-'.$name"
{{ $attributes->merge(['class' => "shrink-0 {$size}"]) }}
/>
Call sites become uniform and refactorable:
<x-app-icon name="add" class="text-indigo-600" />
<x-app-icon name="trash" size="h-4 w-4" class="text-red-600" />
This is the highest-leverage pattern in the package. It gives you one place to change the prefix, one place to add aria-hidden, and one place to enforce a size scale.
Data-driven icons (status maps, nav, action menus)
Keep icon names in a config array or enum, not in @if chains:
// config/ui.php
return [
'status_icons' => [
'active' => 'check',
'pending' => 'time',
'failed' => 'close',
'unknown' => 'info',
],
];
<span class="inline-flex items-center gap-1.5">
<x-app-icon
:name="config('ui.status_icons')[$user->status] ?? 'info'"
size="h-4 w-4"
class="text-{{ $user->status === 'failed' ? 'red' : 'gray' }}-500"
/>
{{ ucfirst($user->status) }}
</span>
Note the interpolation caveat: blade component tags do not support {{ }} inside the tag name. Always route dynamic names through <x-dynamic-component> (as the wrapper above does), never <x-css-gg-{{ $name }} />.
Reusable UI surfaces
<x-app-icon name="home" /> in sidebar links; add aria-current="page" on the <a>, not the icon.size="h-16 w-16") in text-gray-300.<button aria-label="Delete"> and mark the icon aria-hidden="true".Client-side toggling (Livewire / Alpine)
Icons are rendered server-side, so Alpine cannot swap a name. Render the candidates and toggle visibility, or swap them with Livewire state:
<div x-data="{ open: false }">
<x-app-icon x-show="!open" name="chevron-down" size="h-4 w-4" />
<x-app-icon x-show="open" x-cloak name="chevron-up" size="h-4 w-4" />
</div>
In Livewire, prefer a computed property returning the icon name and pass it through the wrapper — the re-render cost is trivial compared with a full page reload.
Testing
Do not assert on SVG geometry. Assert the accessible outcome, and if you must assert markup, use assertSee(..., false) so the escaped HTML matches:
$response->assertSee('aria-label="Delete"', false);
$response->assertSee('<svg', false);
Confirm the prefix before scaling up. The component prefix is the one thing worth verifying from source on day one. A wrong prefix produces "Unable to locate a class or view" errors that look like a broken install but are just a naming mismatch.
class only works if the icon forwards attributes. If a published file lacks {{ $attributes }} on its <svg> root, your Tailwind classes are dropped silently. Read one icon file during setup. If forwarding is missing, publish the views and add it, or wrap the icon in a <span> and style the span.
Tailwind will not scan vendor/. Any utility class baked into the package's own icon Blade files will not be generated by Tailwind's content scanner. Keep all styling in your application templates. This is why the wrapper-component pattern is safer: the classes live in resources/views/components/, which Tailwind does scan.
Inline SVG has a per-instance cost. Each icon is a separate Blade render and an inline <svg>. That is fine for a nav and forms; it is measurable in a 200-row table with three icons per row. If a list page feels slow, cache the rendered fragment (@cache or a computed HTML string) or inline a small sprite for the hot icons rather than calling the component per row.
Icon names are filenames, not CSS.gg names. Names with digits, dots, or reserved words may be renamed in the package. Grep the component directory rather than trusting the website's copy-to-clipboard. Component name collisions with other icon packages are also possible — if you run Heroicons or Feather alongside this, keep prefixes distinct and prefer the wrapper component so a collision is one edit, not fifty.
Accessibility is your job, not the package's. Decorative icons need aria-hidden="true"; meaningful icons need role="img" plus aria-label (or a <title>, but aria-label is easier to pass through the attribute bag). Bake aria-hidden into the wrapper and override it where needed.
Compiled views and vendored changes. After publishing views, upgrading the package, or editing the wrapper, run php artisan view:clear. In production deploys, run php artisan view:cache after composer install; a stale compiled view is the most common "my icon changed but the page didn't" cause.
Version pinning. Small package, single maintainer, active releases. Pin to a minor range and read the changelog before jumping majors — icon files can be renamed, and a rename is a silent 500 on any view that references the old name. Add one smoke test that renders a page using several icons so a rename fails CI rather than production.
Extension points. The package is MIT and tiny: publish and override individual icon views, fork it for a branded set, or register your own anonymous component namespace if you need to rename icons. For anything beyond styling, editing the source is cheaper than fighting the abstraction — there is no plugin API to learn.
Debugging checklist. Icon missing → check the filename exists in the component directory. Icon renders but unstyled → check attribute forwarding. "Unable to locate" error → check the prefix in the service provider and run php artisan view:clear. Icon renders huge → an <svg> without width/height/viewBox attributes will fall back to intrinsic sizing; force h-5 w-5 and confirm the class actually landed.
How can I help you explore Laravel packages today?