Blade Majestic Icons Laravel Package

Getting Started

1. Install (one line, no provider registration).

composer require codeat3/blade-majesticons

Auto-discovery registers the service provider; the provider calls Blade::anonymousComponentPath() against the vendored SVG directory. There is no publish step required, no .env entry, no Vite/npm change.

2. Find the component name — from the filesystem, not the vendor website.

ls vendor/codeat3/blade-majesticons/resources/svg | head -50
ls vendor/codeat3/blade-majesticons/resources/svg | grep home

Every home-line.svg becomes <x-majesticons-home-line />; every home-solid.svg becomes <x-majesticons-home-solid />. The filenames are the API. Vendor marketing names and site search terms frequently differ from the shipped filename (arrow-right, arrow_right, arrowsm-right are all plausible guesses — only one is real).

3. First render.

<x-majesticons-home-line class="size-5 text-gray-500" />
<x-majesticons-home-solid class="size-5 text-indigo-600" />

class and any other HTML attribute pass through to the root <svg>. Icons are inline SVG using currentColor, so Tailwind text colour, dark:, and group-hover: all apply with no extra plumbing.

4. First real use case: replace one hand-pasted inline <svg> blob in your shared layout/nav. Don't start with a sweeping migration — land one surface, confirm it renders and sizes correctly against your existing icons, then standardise.

Implementation Patterns

Wrap it before you spread it. The single highest-value hour you'll spend is an app-level wrapper. Without it, class="size-5 shrink-0" drifts across hundreds of call sites within a sprint.

{{-- resources/views/components/icon.blade.php --}}
@props(['name', 'variant' => 'line'])

@php
    $component = "majesticons.{$name}-{$variant}";
@endphp

<x-dynamic-component
    :component="$component"
    {{ $attributes->class(['size-5 shrink-0']) }}
    aria-hidden="true"
    focusable="false"
/>

<x-icon name="home" />
<x-icon name="trash" variant="solid" class="size-4 text-red-600" />

Note this deliberately hides the package's naming from the rest of the codebase — swapping icon families later becomes a one-file change.

Constrain data-driven names. Any icon name that comes from a DB row, CMS field, nav table, or API payload must go behind an enum or allow-list. Component names are free strings; a bad value is a runtime exception on a production page, not a build error.

enum NavIcon: string {
    case Home = 'home';
    case Users = 'users';
    case Settings = 'cog';

    public function variant(): string { return 'line'; }
}

<x-icon :name="$item->icon->value" :variant="$item->icon->variant()" />

If you can't fully enum it (user-editable icon pickers), validate against a cached manifest generated from the SVG directory and fall back to a default icon instead of throwing.

Loops and menu arrays.

$links = [
    ['label' => 'Dashboard', 'icon' => 'home',        'variant' => 'line'],
    ['label' => 'Billing',   'icon' => 'credit-card', 'variant' => 'solid'],
];

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

State and interaction styling. Because the SVG inherits currentColor, hover/active/dark states are pure Tailwind on the parent — no per-icon styling props:

<button class="group text-gray-500 hover:text-indigo-600 dark:text-gray-400">
    <x-icon name="heart" class="group-hover:scale-110 transition" />
</button>

Testing. Assert on rendered markup, not on component internals:

$this->get('/')
    ->assertSee('majesticons', false)
    ->assertSee('aria-hidden="true"', false);

For a wrapper with an allow-list, add a unit test that iterates the enum and renders each case — this catches renames on package upgrades (there are none in 2.3.0, but future majors are unproven).

Migration from inline SVG / icon font. Run it high-traffic-surface-first (nav, buttons, empty states, flash messages) behind the wrapper. Do a visual pass on layout-critical screens: stroke-based line icons and fill-based solid icons do not share metrics with an icon font, so vertical alignment and optical weight will shift.

Gotchas and Tips

A typo is a runtime 500, not a compiler error. Unable to locate a class or view for component [majesticons.homeline] will surface only when that view renders. In data-driven paths this is a latent production defect — the allow-list is the fix, not a follow-up.

Variants are separate components and coverage is asymmetric. home-line existing does not mean home-solid exists. Check the directory for both before designing a toggle. This is the most common first-hour confusion.

Don't edit vendor/. Any patch to a vendored SVG or generated component is destroyed on the next composer install. Override by defining your own component under resources/views/components/majesticons/<name>.blade.php (app components take precedence), or better, copy the SVG in and own it.

No config file to publish in the current line. Teams expecting config/blade-majesticons.php for prefix/size defaults should be redirected to the wrapper component. Treat the wrapper as your config surface.

Accessibility is yours. The package adds no aria-hidden, no role="img", no <title>. Decorative icons need aria-hidden="true" (set it in the wrapper, as above). Meaningful icons need a label on the interactive parent (aria-label on the button/link), not on the SVG.

Never in email or PDF. Inline SVG is stripped by Gmail and only partially supported by DomPDF/mPDF. Use a PNG or a hosted image for transactional email; treat this package as web-UI-only and write that boundary down.

Sizing: pass class="size-5" (Tailwind 3.4+) or w-5 h-5. CSS width/height beats the SVG's width/height presentation attributes, so this works — but don't try to override viewBox.

Attribute bleed on line icons. Passing stroke-width="1.5" lands on the root <svg> and only helps if the inner paths don't set their own. Verify in devtools before relying on stroke customisation; if you need it globally, do it in your wrapper or vendored copy.

Composer constraint is reactive to Laravel majors. 2.3.0 is a compatibility-only release (widened illuminate/* for Laravel 13) with no API or markup changes — anything written against 2.2.x works unchanged. But support lands after each Laravel major ships. On a Laravel 13 target you must be on ^2.3 or resolution fails; on future majors, budget a gap window and sequence the package bump before the framework bump so you find out early.

Clear view cache after touching components. php artisan view:clear when you add/rename wrapper or overriding components, or you'll debug a stale render.

Bundle discipline. Only rendered icons reach the HTML — you pay per icon instance, not per icon library. In icon-heavy lists or Livewire components that re-render frequently, this inflates the HTML payload; prefer a sprite or a smaller set of icons on the hottest paths.

Icon-library sprawl is the real long-term cost. This is one of a large family of near-identical blade-* packages by a single maintainer. Standardise on one or two families deliberately, register this in your dependency inventory with an owner and pin policy, and keep the documented fallback (vendor the SVGs, local anonymous component path) written down — the exit costs about a day.