Blade Rpg Awesome Icons Laravel Package

Getting Started

Install. One command, no publish step, no asset build:

composer require codeat3/blade-rpg-awesome-icons

Package discovery registers the icon set with blade-ui-kit/blade-icons and generates one Blade component per glyph. There is nothing to npm install, no font to host, and no config you must touch to render your first icon.

The naming rule. Every upstream RPG Awesome class maps 1:1 to a component by dropping the ra- prefix and keeping the rest verbatim:

The prefix rpg-awesome is configurable in the package config (publish it with php artisan vendor:publish --tag=blade-rpg-awesome-icons if you need to change it).

Where to look first. The authoritative list of valid names is the shipped SVG directory — check vendor/codeat3/blade-rpg-awesome-icons/resources/svg and read the filenames. Do not guess from memory of the CSS cheatsheet; a wrong name is a runtime ComponentNotFoundException, not a silent blank. Browse the visual set at the upstream RPG Awesome cheatsheet, then confirm the exact filename in vendor/.

First use case. A character-sheet or stat panel — the canonical fit:

<div class="flex items-center gap-2">
    <x-rpg-awesome-swords class="size-5 text-amber-500" />
    <span class="font-semibold">{{ $character->attack }}</span>
</div>

Attributes you pass land on the root <svg>, so Tailwind sizing/color classes work exactly as you'd expect. Glyphs are single-path and inherit currentColor, so text-* colors them.

Implementation Patterns

Let the attribute bag do the work; never wrap in a sized <span>. Inline SVG participates in flex/grid directly. If you find yourself adding a wrapper div just to size the icon, you're fighting the component — pass class="size-5" instead.

Centralise via a thin wrapper component. Ninety percent of the day-to-day benefit comes from one project-owned component that fixes sizing, accessibility, and the prefix in a single place:

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

<x-dynamic-component
    :component="'rpg-awesome-'.$name"
    :aria-hidden="is_null($label) ? 'true' : 'false'"
    :role="is_null($label) ? null : 'img'"
    :aria-label="$label"
    {{ $attributes->class('size-5 shrink-0') }}
/>

Call sites become <x-game-icon name="shield" class="text-sky-400" />, and the prefix only exists in one file. If you ever vendor the SVGs or drop the package, you rewrite one component instead of grepping every template.

Map domain concepts to icons in PHP, not in Blade. Keep icon names next to the concept they represent so a rename is a one-line diff:

enum DamageType: string
{
    case Fire = 'fire';
    case Slashing = 'swords';

    public function icon(): string
    {
        return 'rpg-awesome-'.$this->value;
    }
}

<x-dynamic-component :component="$hit->type->icon()" class="size-4" />

Note x-dynamic-component needs the full component name including the prefix — it does not resolve short names the way the static <x-rpg-awesome-… /> syntax does.

Use @svg when you need a string, not a tag. blade-icons gives you a directive and a helper for contexts where you can't write a component tag (concatenated HTML, a PDF/DOM builder, a cached fragment):

@svg('rpg-awesome-crown', 'size-6 text-yellow-400')

$html = svg('rpg-awesome-castle')->toHtml();

Build a picker, not free-text icon input. If an admin can choose an icon for a badge or category, validate against the actual filename list rather than trusting the string:

public function rules(): array
{
    return ['icon' => ['required', Rule::in(self::iconNames())]];
}

private static function iconNames(): array
{
    return cache()->rememberForever('rpg-awesome:names', fn () => collect(File::files(
        base_path('vendor/codeat3/blade-rpg-awesome-icons/resources/svg')
    ))->map->getFilenameWithoutExtension()->values()->all());
}

That list is frozen (see Gotchas), so rememberForever is genuinely safe.

Compose freely with Livewire and Alpine. The component is pure server-rendered markup with no JS and no state. Use it inside wire:click buttons, toggled panels, x-show blocks — nothing special required, and it re-renders correctly on Livewire updates.

Coexist with legacy <i class="ra ra-…"> markup. Both render equivalent glyphs. Migrating template-by-template on normal change cadence is the sane path; there is no big-bang rewrite and no data to migrate.

Gotchas and Tips

Unsized inline SVG will happily blow up your layout. The SVG carries a viewBox; if you never constrain it, it can expand to fill its container. Always pass class="size-5" (or width/height). This is the single most common "why is my page broken" first-contact bug.

No accessibility by default — and that's on you. The component gives you a name, not semantics. Adopt a house rule now: decorative glyphs get aria-hidden="true"; meaningful ones get role="img" plus aria-label. Retrofitting this after an audit is tedious; the wrapper component above makes it free.

"Unable to locate a class or view for component" is almost always one of four things: (1) a typo that doesn't match a filename in resources/svg; (2) a missing prefix in an x-dynamic-component call; (3) a stale blade-icons cache in a deployed environment — run php artisan icons:cache as part of your deploy (and icons:clear when debugging); (4) a cached config from before you published or edited the package config — php artisan config:clear.

Confirm the composer constraint before you pin it. ^1.7 is the Laravel 13-compatible line; ^1.6 on Laravel 11/12 installs. Check that the constraint is additive (^10|^11|^12|^13) rather than a floor raise before propagating it across a fleet — otherwise adoption is silently coupled to the framework upgrade. Also watch for conflicts if you co-pin another blade-icons-based package at a different major.

The inventory is frozen — verify coverage before you promise a design. Upstream RPG Awesome is a finished artwork set. New glyph requests mean vendoring a custom SVG, not waiting for a release. Similarly, the set is themed: it has swords, shield, castle, bubbling-potion, but no shopping cart or dashboard glyph — mixing sets is the normal answer, and if you set 'default' => 'rpg-awesome' in config/blade-icons.php to drop the prefix, remember that this creates ambiguity the moment you add a second set.

Don't ship these in email. Inline SVG support across email clients is poor. Use the raw SVG as an <img src> or a PNG instead if themed icons appear in transactional mail.

Not for Inertia/React/Vue front-ends. If Blade isn't your render layer, consume the upstream SVGs directly — the component has nothing to offer there.

Performance is page-weight, not runtime. Each icon is duplicated inline markup. That's a win over an icon font (no extra request, no font-src CSP exception, no FOUT) but a loss if you render hundreds of icons per page in a table — the payload adds up. Render what's visible and prefer the wrapper's fixed sizing so you don't accidentally load a full sheet of glyphs per row.

Test the contract, not the path data. Asserting on SVG <path d="…"> output makes tests brittle against any package update. Assert instead on your own observable contract — an aria-label, a data-* attribute, or the wrapper component's presence.

Extension point and exit ramp are the same move. Publish the config, point path at your own SVG directory, drop in extra icons or replace existing ones, then re-run php artisan icons:cache. That's also the documented exit: vendoring the set and removing the composer require is hours of work, which is exactly why it's safe to adopt for cosmetic surfaces today.