Blade Lucide Icons Laravel Package

Getting Started

Install via Composer (this release is the 2.x line — package v2.0.31, bundling Lucide icons 1.59.0):

composer require mallardduck/blade-lucide-icons --update

First Use Case: Replace a generic icon in your Blade view with a Lucide icon:

<!-- Before -->
<i class="fa fa-user"></i>

<!-- After -->
<x-lucide-user />

Key Starting Points:

1. Icon Explorer: Preview all available icons at lucide.dev. Icon names map kebab-case and camelCase both work (lucide-user → <x-lucide-user />, lucide-user-check → <x-lucide-user-check />).
2. Check what changed: v2.0.31 pulls in Lucide 1.59.0, which adds 5 new icons and modifies 1 existing icon on top of the 1.57.0 set shipped in 2.0.29. The added icons are additive and safe; the single modified icon changes its SVG path, so eyeball it if you use it in tightly-aligned UI. If you track icon updates, diff your used icons against the Lucide releases page.
3. Caching: Enable Blade Icons caching for performance:

   php artisan vendor:publish --provider="BladeUI\Icons\BladeIconsServiceProvider" --tag="blade-icons-config"
   

   Then set 'cache' => true in config/blade-icons.php.
4. Upgrading: From 2.0.29 → 2.0.31 this is a drop-in patch — composer update, clear caches, done. From 1.x it's a major version jump (1.26.x → 2.0.x): budget a full cache clear and a visual smoke test of icons in critical views before shipping.

Implementation Patterns

1. Component-Based Usage

Pattern: Use Lucide icons as Blade components with dynamic attributes:

<!-- Basic usage -->
<x-lucide-home class="text-blue-500 w-6 h-6" />

<!-- Attribute pass-through (width, height, stroke-width, aria-*) -->
<x-lucide-settings class="w-5 h-5" stroke-width="1.5" />

Workflow:

• Icon Selection: Pick from lucide.dev, then confirm the component resolves (php artisan view:cache will surface unknown components early).
• Styling: Pass Tailwind/utility classes directly (text-gray-400 hover:text-gray-600).
• Sizing: Prefer w-* h-* over hardcoded width/height so icons scale consistently; the component respects attributes passed in.

2. Reusable Icon Components

Pattern: Wrap icons in your own component when there's conditional logic:

{{-- resources/views/components/status-icon.blade.php --}}
@props(['status'])

<x-dynamic-component
    :component="$status === 'active' ? 'lucide-check-circle' : 'lucide-x-circle'"
    {{ $attributes->merge(['class' => 'w-4 h-4']) }}
/>

Use Case: Standardise status indicators, nav items, and buttons. Using <x-dynamic-component> (rather than string-concatenating <x-lucide-{{ ... }} />) is safer and lets you merge attributes.

3. Raw SVG Integration

Pattern: Publish the SVGs and use them where Blade components don't exist (JS, email bodies, PDFs):

php artisan vendor:publish --tag=blade-lucide-icons --force

<img src="{{ asset('vendor/blade-lucide-icons/activity.svg') }}" alt="Activity" width="24" height="24" />

Tip: Re-publish after every package update so the on-disk SVGs match Lucide 1.59.0 — otherwise emails/PDFs render stale artwork (and miss the 5 new icons).

4. Configuration Customization

Pattern: Publish the package config to set a default class and caching:

php artisan vendor:publish --tag=blade-lucide-icons-config

// config/blade-lucide-icons.php
return [
    'class' => 'w-5 h-5 text-gray-500',
];

Result: All icons inherit w-5 h-5 text-gray-500 unless overridden per-usage. Keep this file in source control so upgrades don't silently overwrite your defaults.

5. Dynamic Icon Loading

Pattern: Drive icon names from data (database, CMS, enum):

@foreach($items as $item)
    <x-dynamic-component :component="'lucide-'.$item->icon" class="w-4 h-4 mr-2" />
    {{ $item->name }}
@endforeach

Tip: Store bare names (user, activity) in the DB, not lucide--prefixed strings. Validate them against an allow-list in a form request so bad data doesn't blow up rendering — x-dynamic-component throws on a missing component, whereas a plain <x-lucide-foo /> fails at compile time.

Gotchas and Tips

Pitfalls

1. Caching After Upgrade:

   • Gotcha: New icons (including the 5 added in Lucide 1.59.0) don't appear, or old SVGs persist, because compiled views/icon caches are stale.
   • Fix: After composer update, run:

     php artisan view:clear && php artisan config:clear && php artisan cache:clear
     

2. Icon Name Mismatches:

   • Gotcha: Typos (<x-lucide-userr />) or using an icon that was renamed/removed upstream in a Lucide major release.
   • Fix: Verify names against lucide.dev; rely on IDE completion via barryvdh/laravel-ide-helper or a Blade component index. Add a smoke test that renders every icon you reference.

3. Silent Visual Drift on Patch Bumps:

   • Gotcha: Even a patch release like 2.0.31 can ship modified artwork — Lucide 1.59.0 touches 1 icon. Stroke geometry changes shift optical alignment in dense layouts (tab bars, table cells, badge stacks).
   • Fix: Keep a "critical icons" list and snapshot-test rendered markup, or screenshot-diff those components in CI. Don't assume patch = pixel-identical.

4. SVG Asset Paths:

   • Gotcha: Hardcoded relative paths to published SVGs break in non-web contexts.
   • Fix: Always use asset('vendor/blade-lucide-icons/...'). Note the publish path is package-relative — confirm the actual folder name in public/vendor/ after publishing.

5. Build Pipeline:

   • Gotcha: Icons missing in compiled/emailed output because SVGs weren't re-published after the update.
   • Fix: Add php artisan vendor:publish --tag=blade-lucide-icons --force to your deploy script, or switch static contexts to inline SVG output.

Debugging Tips

1. Missing Icons:

   • Inspect the compiled view output (view source) for <svg> tags. No <svg> → the component name didn't resolve (typo or icon not in the set).
   • Cross-check the icon exists in Lucide 1.59.0 on lucide.dev.

2. Styling Not Applying:

   • Lucide icons default to stroke="currentColor" and no fill. Colour via text-* classes, not fill-*.
   • Tailwind purge will drop classes generated dynamically (text-{{ $color }}-500). Use full class names in a lookup map, or safelist them.

3. Performance:

   • Enable 'cache' => true in config/blade-icons.php for production.
   • For pages with dozens of repeated icons, @once-wrap inline SVGs or rely on the icon cache — inline SVG output inflates HTML payloads fast.

4. Accessibility Regression:

   • Decorative icons should be aria-hidden="true"; meaningful ones need role="img" plus a <title> or a visually hidden label. Easy to lose when batch-replacing icons.

Extension Points

1. Custom / Private Icons:

   • Register your own icon set alongside Lucide rather than overriding the package:

     // config/blade-icons.php
     'sets' => [
         'default' => ['path' => 'resources/svg', 'prefix' => 'icon'],
         'lucide'  => ['path' => 'vendor/mallardduck/blade-lucide-icons/resources/svg', 'prefix' => 'lucide'],
     ],
     

   • Prefer a separate prefix so package upgrades don't collide with your icons.

2. Aliases / Compatibility Shims:

   • When an icon is renamed upstream, publish your own SVG under the old name (or add an alias in config/blade-icons.php) so views keep working without a find-and-replace across the codebase. Do this before deleting anything on a major bump.

3. Dark Mode:

   • Tailwind's colour utilities drive Lucide via currentColor:

     <x-lucide-moon class="text-gray-700 dark:text-yellow-300" />
     

4. Sizing Consistency:

   • Define a small set of size classes (w-4 h-4, w-5 h-5, w-6 h-6) in a component or config default, and never pass raw width/height inline — it keeps icon metrics uniform across the app.

5. Tracking New Icons:

   • This release adds 5 new icons with Lucide 1.59.0. Browse the Lucide changelog to see what landed, then grep your codebase for "icon hacks" (text glyphs, Font Awesome remnants) these could replace. Budget a small design pass rather than adopting all 5 blindly — half of new Lucide icons rarely earn their place in a nav.

6. Pinning and Upgrade Cadence:

   • Because the package bumps Lucide frequently (1.57.0 in 2.0.29 → 1.59.0 in 2.0.31, weeks apart), treat icon updates as a routine chore: pin mallardduck/blade-lucide-icons to a caret range, run composer update on your schedule, and always follow with the cache-clear + re-publish steps above.

7. Keeping the Assessment Honest:

   • Version numbers drift fast here (1.23.0 → 1.26.27 → Lucide 1.57.0 on 2.0.29 → Lucide 1.59.0 on 2.0.31). Anchor decisions to the versions in composer.lock, not to marketing copy — and re-check this document whenever the package crosses a major boundary or a release flags modified icons.