Blade Cryptocurrency Icons Laravel Package

Getting Started

Install and confirm the dependency graph first.

composer require codeat3/blade-cryptocurrency-icons
composer show blade-ui-kit/blade-icons codeat3/blade-cryptocurrency-icons

The second command matters more than the first. This package is a thin wrapper: it ships SVG files plus a registrar that hands them to blade-ui-kit/blade-icons. If your app already uses blade-heroicons, blade-tabler-icons, or any other set, Composer resolves one blade-icons version for all of them, so check whether the install silently moved it. composer why-not blade-ui-kit/blade-icons <version> shows who is holding it back.

Where to look first (in this order):

1. vendor/codeat3/blade-cryptocurrency-icons/resources/svg/ — the authoritative list of what you can render, and the exact filenames that become component names. Grep this directory instead of guessing tickers.
2. config/blade-icons.php — if published, it controls the set's prefix, class defaults and fallback. If it isn't published, the package's own defaults apply and you likely don't need to touch it.
3. One SVG file — read it. Confirm whether the fill is currentColor (so Tailwind text colors work) or a hardcoded brand hex. This single detail determines whether your dark mode needs any work at all.

First use case — a market row. Drop it into an existing table loop:

<td class="flex items-center gap-2">
    <x-cryptocurrency-icon-btc class="size-6" aria-hidden="true" />
    <span class="font-medium">BTC</span>
</td>

Serve the page, view source, confirm you see an inline <svg> and not a broken image or a Component not found exception. That's the whole smoke test. No publishing step, no build step, no config.

Implementation Patterns

Never render from a raw ticker. Component names are symbol-based, and symbols are not unique across the market. This is the difference between a cosmetic bug and a trust bug in a financial UI. Resolve from your own canonical asset ID:

{{-- app-wide helper / view model, not in the template --}}
<x-cryptocurrency-icon-btc />

// app/Support/CryptoIcon.php
final class CryptoIcon
{
    public static function component(string $assetId): string
    {
        return 'cryptocurrency-icon-' . (config("assets.icons.{$assetId}") ?? 'generic');
    }
}

<x-dynamic-component :component="CryptoIcon::component($holding->asset_id)" class="size-5" />

The mapping table is yours; the package only renders the leaf. Keep it in config or the DB so a rebrand is a one-line change rather than a search-and-replace across templates.

Wrap it in your own component. One small wrapper pays for itself the first time you need a fallback, an a11y label, or a library swap:

{{-- resources/views/components/coin-icon.blade.php --}}
@props(['asset', 'size' => 'size-5'])

@php $name = \App\Support\CryptoIcon::name($asset); @endphp

@if ($name && \App\Support\CryptoIcon::exists($name))
    <x-dynamic-component :component="'cryptocurrency-icon-'.$name" {{ $attributes->merge(['class' => $size]) }} aria-hidden="true" />
@else
    <span {{ $attributes->merge(['class' => $size.' inline-flex items-center justify-center rounded-full bg-gray-200 text-[10px] font-bold text-gray-600']) }}>
        {{ strtoupper(substr($asset->symbol, 0, 3)) }}
    </span>
@endif

Back exists() with a whitelist you generate once (or cache) by scanning the vendor SVG directory, rather than trusting the ticker at request time. A missing icon must degrade to a placeholder, never to a 500 in a customer-facing screen.

Sizing and theming. Pass Tailwind size-* classes; the SVG scales cleanly with no extra work. For color, use the parent's text color (text-orange-500 on the wrapper) if the SVGs are currentColor-based. For icon-only contexts (nav items, filters, badges) add aria-label or a visually hidden name; for icons sitting next to the ticker text, aria-hidden="true" is correct.

Cache the icons in production. Blade Icons serialises components for faster resolution:

php artisan icons:cache    # verify exact command name via `php artisan list | grep icons`
php artisan icons:clear

Add the cache command to your deploy script and the clear to your local dev loop after adding any icon.

Test one render, and be done. That single assertion is the only automated guard that catches the realistic failure (a Blade Icons bump breaking registration):

it('renders a crypto icon', function () {
    $this->blade('<x-cryptocurrency-icon-btc />')
        ->assertSee('<svg', false);
});

Where it doesn't fit. SPA/API frontends (you need the raw assets, not a Blade wrapper), and HTML email. Inline SVG is stripped by Gmail and several Outlook builds — for receipts and invoices, render a PNG fallback instead and keep the component for web surfaces.

Gotchas and Tips

• Symbol collisions are the real hazard. Multiple tokens share symbols; some tickers start with a digit or contain characters that aren't legal in a component tag. Alias those in your own mapping layer rather than trying to name the component directly.
• Staleness is invisible to tooling. composer audit will never tell you a logo is wrong or a token is missing. Budget a recurring check that the assets you display actually exist in the set — a quarterly grep against your asset registry is enough.
• For missing tokens, publish the set rather than forking. Publish the SVGs into resources/svg/, drop in your own following the same filename convention, and clear the icon cache. Understand the tradeoff: you now own those additions and must re-apply them when the package updates. Keep your additions in a separate, documented folder if the publish path allows.
• Inline SVG has a payload cost proportional to row count. A 200-row market table at ~1–2 KB per mark is 200–400 KB of un-gzipped HTML. If you see that, deduplicate repeated marks into a sprite <symbol> set and <use> them, or virtualise the table.
• blade-icons is the actual upgrade blocker, not Laravel. When a Laravel major lands, this package usually follows quickly (1.9.0 was a Laravel 13 compatibility PR). The realistic failure is a transitive downgrade of blade-icons conflicting with another icon set. Settle it with composer why-not before merging, and land the icon package bump as its own PR, separate from the framework upgrade.
• Validate on your lowest supported Laravel, not just the newest. A widened constraint (^9|...|^13) can mask a regression on an older major that your CI never renders.
• Component resolution is version-sensitive. Prefer <x-cryptocurrency-icon-btc /> (the canonical set-prefixed tag) unless you've confirmed the name-prop form works on your resolved Blade Icons major. If you need to shadow a name, use a distinctly named wrapper instead of an identically named anonymous component — resolution order between app and package components is not something you want to depend on.
• The MIT license covers the code, not the marks. Crypto and exchange logos are third-party trademarks with their own usage guidelines. Bundled SVGs mean zero runtime dependency on a logo CDN — good for CSP, air-gapped builds and privacy review — but it does not settle the trademark question. Raise it at adoption, not at the first customer screenshot.
• Debugging checklist when an icon renders blank: is the filename in vendor/.../resources/svg/ (case-sensitive on Linux, forgiving on macOS — classic "works locally" bug)? Did you clear the icon cache after adding a file? Is the SVG fill hardcoded white, making it invisible on a white card? Is the component name a valid tag? Answer those four and the issue is nearly always found.
• Extension points worth knowing: publish config/blade-icons.php (set prefix, default classes, global fallback), publish the SVG set (add/override icons), and wrap everything behind your own component (swap the library without touching a template). Everything else — no credentials, no scheduled job, no service to operate — has nothing to maintain.