Blade Fluentui System Icons Laravel Package

Getting Started

Install and confirm it's actually wired up.

composer require codeat3/blade-fluentui-system-icons

Auto-discovery registers the icon set; for most apps that is the entire setup. Before writing any markup, read the tagged composer.json — vendor/codeat3/blade-fluentui-system-icons/composer.json — and note three things: the illuminate/* range, the PHP floor, and the blade-icons constraint. That third one matters most day-to-day, because it is shared with every other icon package in your graph (Heroicons, Tabler, Phosphor), and a raised floor there can block a composer update elsewhere.

Where to look first: the filenames. The component names are derived from the SVG filenames shipped in the package:

ls vendor/codeat3/blade-fluentui-system-icons/svg | head -50

That directory is the API. FluentUI glyphs are drawn per size and per variant, so names carry both — expect the shape {name}-{size}-{variant}, e.g. add-24-regular, add-24-filled, rendered as:

<x-fluentui-add-24-regular class="w-5 h-5" />

Verify the exact slug against the vendor listing rather than guessing; the upstream FluentUI icon browser is the place to choose a glyph, but the installed files are the place to confirm the tag.

First use case: one nav item and one button. Drop a single icon into an existing template and check two things in the rendered HTML: (1) is the <svg> sized by your class, and (2) does the fill resolve to currentColor or is it a hard-coded #212121? That second check determines your entire coloring strategy, so do it on day one, not after you've written forty templates.

Implementation Patterns

Direct component use in templates. The common case — navigation, table row actions, status indicators, empty states, settings rows. Keep sizing on the element with utility classes rather than width/height attributes so it stays consistent with the rest of your layout:

<a href="{{ route('settings') }}" class="flex items-center gap-2 text-gray-700 hover:text-gray-900">
    <x-fluentui-settings-20-regular class="w-5 h-5" />
    Settings
</a>

Match the glyph size to the render size. This is the one FluentUI-specific habit worth building. A 16-grid glyph rendered at 24px is a visually lighter icon than a 24-grid glyph rendered at 24px, because Microsoft optically adjusts stroke weight per size. Pick the variant whose native size matches your target (16 for dense table rows, 20 for inline text and nav, 24 for primary buttons and headers) and then scale with CSS only for small deltas.

Wrap it once, before it spreads. The vendor prefix becomes a de facto template API the moment it appears in more than a handful of files. Insulate yourself with a single project-owned component:

{{-- resources/views/components/icon.blade.php --}}
@props(['name', 'variant' => 'regular', 'size' => 20])
@svg("fluentui-{$name}-{$size}-{$variant}", $attributes->merge(['class' => 'shrink-0', 'aria-hidden' => 'true']))

Templates then call <x-icon name="add" />. Swapping icon sets later, or adding a size convention, becomes a one-file change instead of a repo-wide find-and-replace. It also gives you a single place to set aria-hidden defaults and fill-current fallbacks.

Dynamic names: use the directive, not dynamic components. For icon names driven by data (a status map, a config array), @svg() is the reliable path because it resolves through the icon factory rather than Blade's anonymous-component resolution:

@php($statusIcon = ['ok' => 'checkmark-circle-20-filled', 'warn' => 'warning-20-filled'])
@svg("fluentui-{$statusIcon[$row->status]}", 'w-5 h-5 text-current')

Accessibility split. Decorative icons (next to a text label) get aria-hidden="true"; meaningful icon-only buttons get a label and a visually-hidden text alternative. Bake the default into your wrapper, and override per-use:

<button type="button" aria-label="Delete">
    <x-icon name="delete" :size="20" aria-hidden="null" role="img" class="w-5 h-5" />
</button>

Deploy and CI wiring. Add php artisan icons:cache to your deploy script after composer install, and php artisan icons:clear anywhere you already run view:clear / optimize:clear. In tests, add a smoke test that renders a representative sample through the real view path and asserts a 200 plus an <svg in the body — this is your only guard against upstream renames, which fail at render time, not build time.

Gotchas and Tips

A missing or renamed icon is a runtime 500, not a build error. blade-icons throws when it can't resolve a name, and nothing in php artisan view:cache or your asset build catches it. Two mitigations: set a fallback icon in the published config/blade-icons.php so a bad name degrades instead of exploding, and keep the render smoke test in CI. This failure mode is the main reason to pin the minor (^1.35) and let a bot propose bumps you review against the release notes.

Upgrades can silently change the inventory. The package version tracks Microsoft's upstream icon set, not just PHP code. A minor bump can rename or remove glyphs. Skim release notes for renames before merging a bump, and keep icon version bumps in their own PR so a revert is clean.

Stale icon cache after composer update. If icons resolve in local dev but 404/throw in staging, the cached manifest is pointing at paths from the previous version. Run php artisan icons:clear and rebuild. The cache is path-sensitive — it will also break if the deploy directory differs between cache-build time and runtime (common with release-per-directory deploys).

Check whether fill is currentColor or baked in. Microsoft's raw SVGs ship with explicit fill="#212121". If the package doesn't normalize this, text-red-500 will do nothing. Fix once in your wrapper with [&_path]:fill-current or a small CSS rule, and then color exclusively via text-* utilities.

Package discovery is the usual "component not found" culprit. If <x-fluentui-...> throws "Unable to locate a class or view for component", the provider wasn't discovered — typically composer install --no-scripts, a disabled discovery config, or a cached bootstrap. php artisan package:discover then php artisan optimize:clear.

Watch the blade-icons version floor when adding a second icon set. All the wrappers share one core library. Installing this alongside Heroicons can fail resolution if their constraints diverge — resolve this at install time, not later when a security patch forces a blade-icons bump.

Inline SVG is not free at scale. There's no build step and no JS payload, which is the point — but an icon-heavy table can ship hundreds of inline <svg> elements. For genuinely icon-dense screens, consider an SVG sprite (or render the icon once and <use> it) rather than hundreds of copies in the response.

Don't reach for this in Inertia/React/Vue surfaces. Icons there belong in the JS component layer; using both creates two sources of truth for iconography that drift apart. If you need the same glyph names in both places, treat that as an explicit decision with a documented mapping, not an accident.

Extension points worth knowing. Your own wrapper component (above) is the primary one. Beyond that: publish and edit config/blade-icons.php for the global default class and fallback; register your own small sets alongside fluentui for brand marks or a handful of bespoke glyphs; and if the project ever needs to drop the dependency, the exit is mechanical — copy the SVGs you actually use into resources/svg, point the blade-icons sets config at it, and keep the same tag names so no templates change.