Getting Started

Install and pin in one move.

composer require codeat3/blade-microns:^1.7

There is no publish step, no asset build, and no artisan command. Laravel's package auto-discovery registers the service provider and the blade-icons component namespace for you. The entire install is the Composer line above; if you find yourself reading a setup guide longer than that, you're on the wrong page.

Verify the support window before you rely on it. Release 1.7.0 is described in the changelog as exactly one thing: "Laravel 13 compatibility." That phrasing is ambiguous — it could mean the illuminate/* constraint was widened (a free upgrade for everyone) or replaced with ^13 (which leaves Laravel 10–12 projects pinned to 1.6.0 and silently cut off from fixes). Open vendor/codeat3/blade-microns/composer.json and read the require block. That file answers the question; the changelog does not. Commit the lockfile so the answer stays true on every machine.

Where to look first, in this order:

vendor/codeat3/blade-microns/composer.json — PHP and Laravel floor (above).
The package's SVG directory under vendor/ — this is your icon catalogue. There is no autocomplete for component names in most editors, so dump the filenames to a scratch cheatsheet before you design a screen:
```
ls vendor/codeat3/blade-microns/resources/svg | sed 's/\.svg$//' > ~/microns-names.txt
```
The filename maps directly to the component suffix: settings.svg → <x-microns-settings />.
The publishable config — confirm the component prefix really is microns and doesn't collide with another codeat3/blade-* adapter already in the project.
The upstream Microns artwork repository — for the glyph licence, which is a separate question from the wrapper's MIT. Settle it before adoption if anything is customer-facing or redistributed.

First use case: UI chrome, not marketing. Microns is a monochrome, 1px-grid, utilitarian set — it belongs in nav rails, toolbars, table row actions, and empty states. Start there.

{{-- resources/views/dashboard/index.blade.php --}}
<a href="{{ route('settings') }}"
   class="flex items-center gap-2 rounded px-3 py-2 text-sm text-gray-700 hover:bg-gray-100">
    <x-microns-settings class="h-4 w-4 shrink-0 text-gray-500" aria-hidden="true" />
    <span>Settings</span>
</a>

<div class="py-12 text-center">
    <x-microns-inbox class="mx-auto h-10 w-10 text-gray-300" aria-hidden="true" />
    <p class="mt-2 text-sm text-gray-500">No messages yet.</p>
</div>

Sizing and colour are plain HTML and Tailwind utilities passed through to the <svg>. There are no props to learn. A name that doesn't exist throws at render time — loud and immediate, which is the fastest possible feedback loop for typos.

Implementation Patterns

Wrap it once in a project-level `<x-icon>` primitive

The highest-leverage hour you will spend on this package is not sprinkling <x-microns-*> through views. It's building one seam:

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

<x-dynamic-component
    :component="'microns-' . $name"
    {{ $attributes->class($size)->merge(['aria-hidden' => 'true']) }}
/>

<x-icon name="settings" class="text-gray-500" />

Two payoffs. You get one place to own defaults (size scale, aria-hidden, colour tokens). And migration away from Microns becomes a one-file edit — swap the microns- prefix for heroicon-o- or a local component and every call site follows. The package is a thin adapter over blade-icons; treat the icon family as a swappable dependency and this pattern is what makes that true in practice rather than in a slide deck.

Dynamic names from config or data

Icon names usually originate outside the template — a nav definition array, a menu table column. Use x-dynamic-component rather than @switch ladders:

// config/navigation.php
['label' => 'Reports', 'route' => 'reports.index', 'icon' => 'chart-bar'],

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

Status maps: keep the mapping in PHP

For badges and status pills, define the map once in a class or enum and cover it with a test:

// app/Support/StatusIcons.php
final class StatusIcons
{
    public const MAP = [
        'active'  => ['icon' => 'check-circle', 'class' => 'text-green-600'],
        'pending' => ['icon' => 'clock',        'class' => 'text-amber-600'],
        'failed'  => ['icon' => 'x-circle',     'class' => 'text-red-600'],
    ];
}

@php($s = StatusIcons::MAP[$status] ?? StatusIcons::MAP['pending'])
<x-icon :name="$s['icon']" class="{{ $s['class'] }}" />
<span>{{ ucfirst($status) }}</span>

The failure mode to defend against is a glyph being renamed in an upstream re-sync. One map plus a test that renders every entry localises that blast radius to a single file.

Dense tables: think about payload before you scale

Inline SVG duplicates full path data per occurrence. A 200-row table with three icons per row embeds 600 copies of the same markup. For list-heavy screens, define symbols once and reference them:

{{-- resources/views/partials/icon-sprite.blade.php --}}
<svg xmlns="http://www.w3.org/2000/svg" class="hidden">
    <symbol id="i-edit" viewBox="0 0 24 24">
        <x-microns-edit />
    </symbol>
</svg>

<svg class="h-4 w-4 text-gray-500"><use href="#i-edit" /></svg>

Confirm the component emits an <svg> you can nest (it does, but check the wrapper's attributes), or render the raw path from the vendor SVG inside the symbol. Measure the HTML weight delta in the browser before drawing conclusions — the number is the argument either way.

Livewire and Blade class components

Rendering is entirely server-side, so this composes with Livewire and class-based Blade components with zero special handling — the icon re-renders with the rest of the fragment:

<button wire:click="delete({{ $post->id }})" class="text-gray-400 hover:text-red-600">
    <x-icon name="trash" />
    <span class="sr-only">Delete</span>
</button>

Publish the config only when you have a reason

The config exists to change naming or paths. Do not publish it on day one — an unmodified config file checked into the repo is drift risk with no upside. Publish when you hit a genuine prefix collision and document why in the commit message.

Gotchas and Tips

Read the constraint, don't trust the changelog. "Laravel 13 compatibility" is the classic moment a maintainer narrows illuminate/* instead of widening it. Check composer.json; record the answer in your upgrade notes so the next person doesn't re-derive it.

Zero stars / zero dependents is a real signal. No upstream battle-testing, no community to lean on, single maintainer. The de-risking move is cheap and should be written down rather than feared: drop the SVGs you actually use into resources/svg, register them with blade-icons directly, and your fork path is a directory of files plus a provider. Note in your PR which glyphs would need vendoring so an incident doesn't turn into archaeology.

Missing components throw at render. Good: failures are loud and local. Bad: a name you're certain exists becomes a 500 on a page you didn't think you touched. Keep the filename cheatsheet handy and add a test that renders every name in your nav/status maps.

Prefix collisions across icon packages. Every codeat3/blade-* adapter registers into the same x-* namespace. If the project already has Heroicons or another adapter, confirm the microns prefix is applied and route everything through your <x-icon> primitive so two families never argue in one template.

Colour comes from currentColor — so text-* is the knob, not fill. Setting fill="red" works until the first hover state, then fights you. Use text-gray-500 / hover:text-red-600 and let the SVG inherit. If you need a two-tone glyph, stop: Microns is a monochrome set and forcing colour into it is the wrong tool.

Accessibility is on you. Decorative icons get aria-hidden="true" — bake it into the <x-icon> primitive so it's automatic. Meaningful icons need an accessible name: a <span class="sr-only"> sibling or a <title> inside the SVG. Icon-only buttons without one are the single most common a11y regression introduced by an icon migration.

Clear compiled views on deploy. Blade components are compiled and cached. In containerised builds, ensure php artisan view:clear (or a fresh cache build) runs so renamed or removed components aren't served from stale compiled views. Verify the behaviour on a read-only filesystem if that's your deploy model.

Pin exactly and treat it as internal tooling. Pin the version, add it to the SBOM, note the rationale. Budget a light review at each Laravel major and at each upstream icon re-sync — a resync can change SVG paths and produce silent visual diffs with no API change to flag them. A visual regression test over a representative page of ~20 icons catches this for almost no effort.

Verify the artwork licence separately from the wrapper's MIT. MIT covers the PHP code. The Microns glyphs are a separate work with their own terms and possible attribution obligations — it matters most when SVGs ship in compiled bundles on a customer-facing surface.

Don't split the icon story across stacks. If a surface is React/Vue-rendered, use upstream Microns SVGs there rather than reaching for this Blade wrapper inside a shell that mostly hosts a SPA. Two sources of truth and two migration problems is worse than picking one and being slightly wrong on the edges.

Scope check. Microns suits dense admin chrome — toolbars, tables, nav, empty states. It is not the family for hero imagery, duotone treatments, or brand marks. If a screen genuinely needs expressive iconography, that's a different conversation; don't stretch this set to cover it.

Blade Microns Laravel Package