Blade Game Icons Laravel Package

Getting Started

Prerequisites. This package is a set provider for blade-ui-kit/blade-icons, not a renderer. Confirm the host app resolves blade-ui-kit/blade-icons (it usually arrives transitively, but check composer show blade-ui-kit/blade-icons). If your app is a pure API service or a JS SPA, stop here — there is nothing for you.

Install.

composer require codeat3/blade-game-icons
php artisan view:clear

No publish step, no config file, no migrations. If a component fails to resolve, view:clear is the first thing you try, not the last.

Where to look first. Before writing any Blade, open the vendor directory and confirm two things: the actual component prefix and the real icon names.

ls vendor/codeat3/blade-game-icons/resources/svg | head -50
ls vendor/codeat3/blade-game-icons/resources/svg | grep -i sword

The published example uses <x-gameicon-sword />, but the registered prefix is a naming decision made by the package, not by you — verify it against the directory listing and a test render rather than trusting the README example blindly. Icon names are the other trap: the catalogue contains crossed-swords, broadsword, sword-wound, sword-brandish — not a clean sword. Grep the directory; do not guess.

First use case. An achievement badge on a profile page is the fastest proof of value:

<x-gameicon-trophy class="w-6 h-6" aria-hidden="true" />

Render it once, confirm the SVG is inline in the HTML source (not an <img> tag, not a network request), then move on to a real surface. If text-red-500 does not tint the icon, read the Gotchas section before you go further — that is the first thing every developer hits.

Implementation Patterns

1. Never hardcode icon names in feature views. The catalogue is large, names are unintuitive, and product owners will want to swap a badge icon without a code review. Keep a semantic map in a config file:

// config/rewards.php
return [
    'achievement' => 'trophy',
    'streak'      => 'flame',
    'level_up'    => 'upgrade',
    'quest'       => 'scroll-unfurled',
    'leaderboard' => 'podium-winner',
    'fallback'    => 'help',
];

2. Wrap the package in one app-level component. This is the single highest-leverage pattern. Every icon in your app goes through one place, so sizing, accessibility, colour, and the fallback for unknown names are decided once:

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

@php
    $icon = config("rewards.$name", $name);
    $component = "gameicon-{$icon}";
@endphp

<x-dynamic-component
    :component="$component"
    {{ $attributes->merge(['class' => 'w-5 h-5 shrink-0']) }}
    :aria-hidden="$label ? null : 'true'"
    :role="$label ? 'img' : null"
    :aria-label="$label"
/>

Usage becomes <x-icon name="streak" class="w-8 h-8 text-orange-500" /> and the rest of the codebase never learns the package's naming convention. When you eventually swap icon sets, you change one file.

3. Data-driven icons need x-dynamic-component. Reward rows from the database will carry an icon key. Resolve it at render time — but whitelist it. Do not interpolate a user-controlled string into a component name; a validated enum column or a config lookup is the correct boundary.

@foreach ($achievements as $achievement)
    <x-icon :name="$achievement->icon_key" :label="$achievement->title" />
@endforeach

4. Accessibility is a per-usage decision, not a component default. Decorative icons next to a text label get aria-hidden="true" and nothing else. Standalone icons that are the only content get role="img" plus aria-label. Passing a <title> child through the component is awkward with blade-icons, so aria-label on the <svg> is the pragmatic path. Bake the convention into the wrapper above and you never have to think about it again.

5. Livewire and Inertia. In Livewire, the icons are just Blade — no special handling, and they re-render with the component. In an Inertia app, they only work inside the root Blade template or any server-rendered Blade partial; inside a Vue/React page they are useless. Do not plan a JS-side icon strategy around this package.

6. Test the render path, not the package. One smoke test catches prefix changes, package upgrades, and config typos:

public function test_badge_icons_render(): void
{
    $this->blade('<x-icon name="achievement" />')
        ->assertSee('<svg', false)
        ->assertSee('aria-hidden', false);
}

7. Migrate incrementally. Replace ad-hoc inline SVGs one surface at a time — a trophy wall or a rewards catalogue is a good beachhead because the icons are the point of the page. There is no cutover obligation and rollback is composer remove plus reverting template references.

Gotchas and Tips

The colour trap. These are inline SVGs, so text-red-500 only works if the paths inherit fill from the parent <svg>. Many game-icons.net exports carry no fill attribute (inherits fine) but some hardcode one. Verify on the very first icon you render: if text-* does nothing, either pass fill="currentColor" on the component or add a CSS rule scoped to your wrapper. Do not assume Tailwind text colour "just works" — this is the number one first-day confusion.

Component prefix ambiguity. The README example (<x-gameicon-sword />) and casual references to <x-game-icons-{name} /> coexist in the wild. Confirm empirically before documenting anything for your team. Standardising the wrong prefix in a wiki is a support burden that outlives the package.

Icon names are not a vocabulary. flame exists, fire does not. podium-winner exists, leaderboard does not. Every feature that needs an icon starts with a grep of the vendor SVG directory — or better, with a shortlist added to your config map so the next developer does not repeat the search.

Visual consistency is a real cost. game-icons.net is community-contributed across thousands of entries with mixed stroke weights, detail levels, and visual density. Do not mix these with Heroicons or Lucide at the same size in the same toolbar — the mismatch is immediately visible. Pick a size scale (w-5 for inline, w-8+ for badges) and a single family per surface, and treat it as a design decision, not a preference.

Licensing is your job, not the package's. CC BY 3.0 requires attribution. The package cannot put a credit line in your footer. Get it onto a legal/about/credits page in the same sprint you adopt it, or it becomes permanent technical debt with a legal edge. Ship it with the feature, not after it.

Do not reach for blade-icons:cache early. It adds a build artifact that must be regenerated on every deploy and becomes a deploy-time failure mode. Introduce it only after profiling shows the render path matters — for a badge wall it will not.

Vendor size. Expect a noticeable bump in vendor/ and Composer install time; this is a cold-deploy and CI-image concern, not a runtime one. Measure it before putting hundreds of icons on a high-traffic page, and remember there is no compile-time subsetting: the whole set ships.

Upgrade coupling you inherit. The package tracks two upstreams at once — the Game Icons catalogue and the blade-icons API. On a Laravel major, check the package's release cadence before the upgrade window closes, and verify transitive constraint changes on a throwaway branch with composer why-not rather than assuming a compatibility-only release is inert. An icon package should never be the thing blocking a framework upgrade.

Escape hatch, keep it in mind. The SVGs are plain files in vendor/. If the package stalls, copy the directory into resources/svg/, register it as your own blade-icons set, and drop the dependency in an afternoon. That is the real risk ceiling here, and it is worth telling the team so nobody treats this as load-bearing architecture.