Blade Pixelarticons Laravel Package

Getting Started

Install with a single Composer command — there is no npm, no asset publishing, and no build step:

composer require codeat3/blade-pixelarticons

Blade component discovery is automatic via Laravel's package auto-discovery (the package is a thin wrapper over blade-ui-kit/blade-icons), so the components are available immediately after install. If they are not, the first thing to run is composer dump-autoload followed by php artisan view:clear — stale compiled views are the usual culprit, not the package.

Where to look first: the icon inventory itself. The package ships the Pixelarticons SVG set inside the vendor directory, so the fastest way to discover valid names is:

ls vendor/codeat3/blade-pixelarticons/svg | head -50

Each foo-bar.svg maps to a component named after it, so home.svg becomes <x-pixelarticons-home /> and arrow-right.svg becomes <x-pixelarticons-arrow-right />. Browse the upstream Pixelarticons gallery for a visual index, then confirm the exact filename in the vendor directory before using it — the set is large and not every name is what you would guess.

First use case: drop an icon into an existing view. Anywhere in a Blade template:

<x-pixelarticons-home class="w-6 h-6 text-slate-500" />
<x-pixelarticons-settings class="w-5 h-5" />

Attributes are passed straight through to the rendered <svg> root, so Tailwind sizing/color utilities, data-* attributes, and inline style all work as you would expect from normal HTML.

Implementation Patterns

Treat icons as components, not files. The single most valuable habit this package enables is never copy-pasting an SVG into a view again. Everything below builds on that.

Attribute passthrough for sizing and color. The rendered <svg> inherits whatever you give it. The cleanest approach is to rely on currentColor by setting the text color on a parent and letting the icon inherit, rather than passing a color attribute per icon:

<a href="/settings" class="flex items-center gap-2 text-gray-700 hover:text-black">
    <x-pixelarticons-settings class="w-5 h-5" />
    <span>Settings</span>
</a>

Wrap it once for app-wide consistency. Rather than repeating class="w-5 h-5" on every call, define a single wrapper component that owns default sizing and the accessibility contract:

{{-- resources/views/components/icon.blade.php --}}
@props(['name', 'size' => 'w-5 h-5'])
<x-dynamic-component :component="'pixelarticons-'.$name" {{ $attributes->class($size) }} />

Then everything in the app uses <x-icon name="home" />. When you later change default size, or swap the underlying set, you change one file. This is the extension point that matters most in day-to-day use.

Data-driven icons. For nav menus, status indicators, and table action columns, store the component name (without prefix) alongside the label and render dynamically:

@foreach ($navItems as $item)
    <a href="{{ $item['url'] }}">
        <x-icon :name="$item['icon']" />
        {{ $item['label'] }}
    </a>
@endforeach

Keep the icon key as a plain string in config/arrays; the x-dynamic-component resolves it at render time. This makes menus and permissions-driven navigation trivial to configure.

Status and semantic mapping. A pattern that pays off in admin panels: map domain states to icon names in one place.

// config/ui.php
'status_icons' => [
    'success' => 'check',
    'warning' => 'warning',
    'error'   => 'close',
    'pending' => 'clock',
],

Rendering from a map keeps the "which icon means what" decision out of templates and makes bulk changes safe.

Caching in the deploy pipeline. blade-icons supports php artisan icons:cache, which resolves all components ahead of time and avoids filesystem scans on the hot path. Add it to your build/deploy step:

php artisan icons:cache

This is especially important on read-only filesystems and serverless PHP (Laravel Vapor, Lambda) — the cache must be warmed at build time, because the runtime cannot write it. Use php artisan icons:clear after adding a package or changing the prefix.

Integration with forms and buttons. Icons inside buttons need to stay decorative and not interfere with the label:

<button type="submit" class="btn">
    <x-icon name="save" aria-hidden="true" />
    Save
</button>

Gotchas and Tips

Pixel art does not scale smoothly — use integer multiples. These are grid-based glyphs. Rendering at odd sizes (e.g. w-[18px]) or applying rounded, CSS filters, or transforms produces fuzzy edges. Stick to integer multiples of the native grid — 24, 48, 72, or explicit w-4 h-4 / w-6 h-6 / w-8 h-8. If edges still look soft, add shape-rendering="crispEdges" as an attribute; pixel sets frequently need it and it is not always baked into the SVG.

The aesthetic is the expensive decision, not the package. Adopting this set commits the product to a retro/pixel look. Swapping to an outline or duotone set later means touching every template that used a component. The package itself is trivially removable; the visual commitment is not. Decide that deliberately before spreading icons across the codebase.

Verify currentColor on the actual SVG. Most icons in this family fill with currentColor, which makes Tailwind text-* coloring work. Confirm on one file before relying on it globally — if the fill is hard-coded, you will need to override it in your wrapper component.

Icon names are not always obvious. Some names contain numbers or unexpected hyphens. A typo produces a Unable to locate a class or view for component exception at render time — not at build time. When that happens, ls vendor/codeat3/blade-pixelarticons/svg | grep <fragment> is faster than searching docs. Consider a feature test that renders every icon referenced in your config maps.

Accessibility needs an explicit decision. Do not assume the rendered SVG carries aria-hidden or a title. For decorative icons, add aria-hidden="true" (or handle it in your wrapper). For icons that convey meaning without a visible text label — icon-only buttons, status badges — provide a label:

<button aria-label="Delete">
    <x-icon name="trash" aria-hidden="true" />
</button>

If your compliance bar is strict, put this in the wrapper component once rather than fixing it per template later.

Prefix collisions and renaming. The config allows changing the component prefix. Decide the prefix once and record it in your frontend conventions doc. If you rename it, run php artisan view:clear and php artisan icons:clear — the cached component registry will otherwise keep serving the old names. Also watch for collisions with your own components if you ever name a component pixelarticons-*.

Pin the exact version. Patch-level releases sync upstream icon changes and can subtly alter glyph shapes. If visual stability matters (branded or pixel-exact UI), use an exact constraint ("codeat3/blade-pixelarticons": "1.7.0") rather than a caret range. 1.7.0 is a pure Laravel 13 compatibility release with no functional change, so it is a safe place to pin.

Sequence the Laravel framework upgrade correctly. Laravel-major support arrives as discrete, hand-cut releases here. Take the package version that supports your target framework before you bump Laravel, so the framework upgrade is never blocked on Composer resolution for an icon package. Because this is a leaf presentation dependency with 2 stars and no community canary, you will be detecting breakage yourself — the fallback (vendoring the SVGs into a local blade-icons path) is a contained refactor rather than a rewrite, so keep that in mind rather than fearing it.

Coverage gaps are real. The set is large but not universal. Before committing to it for a specific screen, inventory the icons that screen needs. If you need only a handful of glyphs and none of them depend on the Pixelarticons look, a local resources/svg directory registered with blade-icons is a lighter dependency — but do not mix two icon systems permanently; overlap only long enough to migrate.