Unicon Laravel Laravel Package

Getting Started

Unicon gives Laravel a single Blade component for icons so you stop hand-copying SVGs into Blade files or wiring up three different icon packages. The value shows up the moment you have a navbar, a sidebar, and a few buttons that all need icons from different sets (Heroicons for UI chrome, Font Awesome for brands, Lucide for consistency) and you want one syntax for all of them.

Install and publish

composer require unicon-rocks/unicon-laravel
php artisan vendor:publish --tag=unicon-config   # confirm tag in README

The config file is the first place to look. It typically holds the default icon set, default CSS classes/size, the local SVG path for your own icons, and any caching toggle. Read it top to bottom before writing any markup — most "why does this render wrong" questions are answered there.

First use case

Drop the component into a Blade view:

<x-unicon name="heroicon-o-home" class="w-5 h-5" />

(Exact component name and set prefixes are defined in the package's README/config — verify both before rollout. The mental model is <x-unicon name="{set}-{style}-{icon}" /> or a set-specific prefix per the config.)

A realistic first slice: replace the hard-coded SVGs in your layout's sidebar and topbar with <x-unicon> calls, keeping the existing Tailwind w-*/h-* classes. That gives you a 1:1 visual diff, and from then on swapping an icon is a one-word edit.

Implementation Patterns

Treat the component as your icon vocabulary layer. The useful abstraction isn't "render an SVG" — it's "I reference icons by a stable name and the package resolves the SVG." Lean into that:

• Config-driven defaults. Set the default set and default classes in config/unicon.php so the 80% case is <x-unicon name="home" /> with no arguments, and only specify set=/class= when deviating.
• A thin app-level wrapper. Create resources/views/components/icon.blade.php that wraps <x-unicon> with your house rules (default w-5 h-5, aria-hidden="true", a shared stroke width). Views then use <x-icon name="..." />, and you can change the underlying icon package or defaults in one file later.
• Dynamic names from data. Because icons are resolved by string, you can drive them from config, enums, or DB rows — e.g. a NavigationItem with an icon column, rendered as <x-unicon :name="$item->icon" />. Add a fallback (see Gotchas) so a bad name doesn't break a page.
• Navigation/menu builders. If you use a menu package or a config array of nav links, store the icon name as a plain string in that array. This is where a universal component earns its keep — the menu doesn't care which icon library is underneath.
• Livewire and Inertia. In Livewire, the component renders server-side like any Blade component; just be aware re-renders will re-resolve the name. For Inertia/SPA pages, Unicon only helps the initial server render — client-side navigation and client-only components need the icon available in the rendered HTML or you need a JS-side icon solution.
• Mail and PDF templates. Inline SVG (which is what these packages usually emit) works in HTML mail far more reliably than icon fonts. This is a genuinely underrated use case: pass the same <x-unicon> into your Mailable views so transactional emails match the app.
• Buttons and links as slots. Where the package supports it, use the icon component inside a button component's slot rather than building icon-left/icon-right props. It keeps the button component small and lets the caller control the icon.

Suggested workflow for a team

1. Publish config, pick one default set, and document the naming convention in the repo's README or a docs/icons.md.
2. Add the app-level <x-icon> wrapper with accessibility defaults baked in.
3. Migrate one area (sidebar) as a proof, then sweep the rest with a search for <svg in resources/views.
4. Add a Blade test that renders a representative page and asserts the icon markup appears — cheap regression protection when someone typo's an icon name.

Gotchas and Tips

• Verify names against the actual source, not memory. Icon names differ between sets and versions (home vs home-outline vs o-home). When an icon silently renders nothing, the name is almost always the culprit. Open the vendor directory or the README's icon index and search the exact string.
• Silent failure is the default. A universal resolver that can't find a name often renders an empty string rather than throwing. Wrap rendering in a dev-only check (log or throw when app()->isLocal() and the icon is missing) or add a fallback icon in the wrapper component so production degrades gracefully.
• Caching is a double-edged sword. If the package caches resolved icons or compiled SVGs, config/path changes may not take effect until you clear it — php artisan cache:clear / view:clear before you start debugging. Conversely, caching inline SVGs across a page with hundreds of icons is what keeps it fast; don't disable it in production.
• Inline SVG bloat. Inline SVGs on a page with 200 icons add real bytes and DOM nodes. For icon-heavy UIs, prefer an SVG sprite/mask approach or keep icons small and reused. Check whether the package offers a sprite or "symbol" mode before you hand-roll one.
• Class passthrough is not automatic. Confirm whether class= is merged onto the root <svg> and whether the package adds its own sizing classes that fight yours. If Tailwind's w-5 loses to an inline width attribute, you'll be chasing phantom sizing bugs.
• Accessibility. Icons are decorative most of the time — default them to aria-hidden="true", and only add role="img" + <title>/aria-label for standalone icon buttons. Baking this into the wrapper (above) prevents the "every icon is announced twice" screen-reader complaint.
• CSP and style attributes. Inline SVGs sometimes carry style or <style> blocks that a strict Content-Security-Policy will block. If you have a CSP, test icons early — otherwise your whole icon layer breaks at deploy time, not in dev.
• Blade component name clashes. If you alias the component or create <x-icon>, make sure it doesn't shadow a package or other component with the same name. Registering your wrapper under a distinct name (<x-ui.icon>) avoids surprises.
• Small ecosystem, so pin and read the source. With ~26 stars, this is a young package: pin the version in composer.json, skim the package's src/ (it's small) before relying on undocumented behavior, and expect breaking changes on minor bumps. Treat the config file and the Blade component class as the source of truth over the README.
• Extension points to look for. Custom icon directories (drop your own SVGs into resources/svg/), registering additional icon sets, per-set default classes, and a programmatic resolver/helper for cases where Blade isn't available (e.g. building strings in a service). If a needed hook doesn't exist, the component is thin enough to patch via your wrapper rather than forking.
• Don't ship it to the frontend blindly. Unicon solves the server-rendered case. If your app has significant client-side rendering (Vue/React islands, Inertia navigation), plan for how those components get icons — usually a matching JS icon package — so you don't end up with two diverging icon vocabularies.