Getting Started

Install and render in under a minute.

composer require codeat3/blade-codicons:^1.35

That is the entire setup. No vendor:publish, no config file, no CSS/JS build step, no Vite or Tailwind plugin, no asset compilation. The service provider is auto-discovered via Laravel package discovery and the components are plain Blade views shipped inside vendor/. If you deploy with php artisan view:cache, make sure it runs after composer install so the newly installed component views get compiled.

Version 1.35.0 is the release that adds Laravel 13 compatibility. If you're on Laravel 10–12 you can use earlier 1.34.x safely; if you're on 13, ^1.35 is the minimum — check with composer why-not codeat3/blade-codicons if resolution fails.

First render:

<x-codicon-save />
<x-codicon-trash class="w-4 h-4 text-red-600" />

Where to look first, in order:

vendor/codeat3/blade-codicons/resources/views/components/ — this is the authoritative list of icon names available in your installed version. The set is auto-generated from upstream VS Code, so this directory beats any README, blog post, or stale docs. ls it, or grep for names when you can't find one.
The VS Code Codicon reference (upstream Microsoft browser) — the source of truth for what each glyph looks like and what Microsoft calls it.
The package README — for the attribute-passthrough convention: whether class lands on the <svg> element directly or on a wrapper <span>.

First use case: pick one developer-facing or admin surface — a sidebar nav, a toolbar, table row actions, an empty state, a status badge. That's where Codicons read as native (they're literally the icons VS Code uses) and where you get the most value per line of markup. Do not start with a marketing page or consumer-facing UI — the icon language will look borrowed.

Before you write your second icon, add a one-line CI smoke test. The most likely silent regression for this package is a version bump that renames, drops, or re-registers a component, and the failure mode is a Blade exception at render time — not a warning, not a build error:

public function test_codicon_component_registers(): void
{
    $this->blade('<x-codicon-save />')->assertSee('<svg', false);
}

Implementation Patterns

The wrapper is the real design decision

Do not let <x-codicon-*> appear scattered across your views. Build one local component that absorbs the vendor, the sizing scale, the accessibility contract, and the name mapping. That turns a future swap to Heroicons, Lucide, or a bespoke set into a one-file change instead of an N-file refactor.

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

@php($component = 'codicon-' . $name)

@if ($label)
    <x-dynamic-component :component="$component" role="img" aria-label="{{ $label }}"
        {{ $attributes->merge(['class' => 'inline-block shrink-0 w-4 h-4 align-text-bottom']) }} />
@else
    <x-dynamic-component :component="$component" aria-hidden="true" focusable="false"
        {{ $attributes->merge(['class' => 'inline-block shrink-0 w-4 h-4 align-text-bottom']) }} />
@endif

Day-one verification: confirm the generated codicon component forwards $attributes onto the <svg> element. If it wraps in a <span> and you can't style the SVG directly, hold the attribute bag on the wrapper instead:

<span {{ $attributes->merge(['class' => 'inline-flex shrink-0 w-4 h-4']) }} aria-hidden="true">
    <x-dynamic-component :component="$component" class="w-full h-full" />
</span>

Semantic names, not vendor names

Map your product's icon vocabulary to Codicon names explicitly, in one config file. Guessing names is where visual regressions come from.

// config/icons.php
return [
    'save'   => 'save',
    'delete' => 'trash',
    'edit'   => 'edit',
    'search' => 'search',
    'open'   => 'folder-opened',
    'branch' => 'git-branch',
];

<x-icon :name="config('icons.' . $action)" />

This also gives you a single file to iterate over in a test that asserts every mapped name actually renders — catching an upstream rename on the next composer update before it hits production.

public function test_every_mapped_icon_renders(): void
{
    foreach (config('icons') as $semantic => $codicon) {
        $this->blade("<x-icon name='{$semantic}' />")->assertSee('<svg', false);
    }
}

Sizing and color

Codicons are drawn on a 16px grid. Stay at 16 or 32 (w-4 h-4, w-8 h-8) for pixel-crisp output; 20px works but inspect the anti-aliasing at your target zoom. Because the SVGs are inline and use fill="currentColor", color is entirely inherited from text color — which means hover, focus, disabled, and dark mode states are free:

<a href="#" class="flex items-center gap-2 text-gray-600 hover:text-gray-900 dark:text-gray-300">
    <x-icon name="settings" />
    <span>Settings</span>
</a>

Always include shrink-0 (baked into the wrapper) — otherwise icons get crushed in flex rows next to long or wrapping labels.

Icon-only buttons

The icon carries the meaning, so it needs a label. Use the role="img" branch:

<button type="button" class="p-1 rounded hover:bg-gray-100">
    <x-icon name="trash" label="Delete record" />
</button>

Migration path

Go screen by screen, not file by file. For each screen: inventory the existing inline SVGs, map each to a codicon name in config/icons.php, replace with <x-icon>, delete the old partial. Then run a visual pass on global layout chrome and nav specifically — an icon that renders fine in a data table but throws in a shared layout takes down the whole app. No data migration, no downtime, reversible per commit.

Integration notes

Livewire: works identically inside component views because there is no JS or runtime state — Livewire's DOM morphing is a non-issue.
Blade UI Kit coexistence: the codicon- prefix keeps component namespacing separate. No collisions.
@include partials and layout files: fine, same as anywhere else. Just remember the wrapper is what you call, not the vendor component.
Frontend frameworks (Inertia/React/Vue): stop. Use the upstream @vscode/codicons npm package — this Blade wrapper adds nothing on that side.

Gotchas and Tips

A missing icon name is a hard failure, not a blank box. <x-codicon-tpyo /> throws Unable to locate a class or view for component at render time — in production, on the page that needed it. The wrapper plus the whitelist test above are the mitigations. Do both.

The generated SVG has no aria-hidden by default. Skip the wrapper and every decorative icon becomes an unlabeled graphic in the accessibility tree. Bake aria-hidden="true" focusable="false" into the default branch of the wrapper so decorative usage is safe-by-default and only labeled usage needs the override.

currentColor can make icons invisible. Anything that sets text-transparent on an ancestor — gradient/clip-text headings, some skeleton loaders, text-white on a white card, disabled states that set opacity-0 instead of opacity-50 — will silently erase the icon. If an icon "disappears," check the inherited text color before you check the markup.

Pin the version and read the diff on bumps. The package is auto-generated from upstream Microsoft's set and ships on a fast patch cadence. Upstream adds, renames, and occasionally drops glyphs; those flow straight into your component names. Pin ("codeat3/blade-codicons": "1.35.0" or a tight caret) and let the CI smoke test plus your name-map test gate every bump.

Deploy ordering matters. Components are Blade views inside vendor/. If your deploy runs php artisan view:cache, it must run after composer install. Stale compiled views after a package upgrade produce "component not found" errors that survive a cache clear if you clear the wrong thing — php artisan view:clear locally, view:cache last in the pipeline.

Watch HTML payload on icon-dense pages. Inline SVG is verbose. A data table with 200 rows × 3 action icons can add six figures of bytes to the response. Measure one real screen during the pilot. If it's material: cut icon count per row, collapse row actions into an overflow menu, or fragment-cache the row partial.

Do not use these in email or Markdown mail. Inline SVG is stripped or unsupported by most mail clients. x-icon will happily render in a mail view and look fine in the browser preview — then break in the actual client.

Codicon coverage is fixed upstream. If a glyph doesn't exist, the answer isn't a PR to this package — it's a design decision. Keep a small local escape hatch (a handful of hand-written SVGs in the wrapper's @switch) rather than forking.

Treat it as a commodity dependency. Single maintainer, auto-generated code, minimal public adoption, bus factor of 1. That's acceptable behind a wrapper and unacceptable with <x-codicon-*> sprinkled through a hundred views. Add "verify blade-codicons Laravel-major compatibility" to your framework upgrade runbook — that's the highest-probability real failure mode, and this release (1.35.0, compatibility-only, no API change) is exactly what that runbook item is for.

Blade Codicons Laravel Package