Blade Zondicons Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require blade-ui-kit/blade-zondicons
   

   This installs the package and its dependency (blade-ui-kit/blade-icons).

2. First Use Case: Render a Zondicon directly in a Blade view:

   <x-zondicon-cloud class="w-5 h-5 text-blue-500" />
   

   Replace cloud with any Zondicon name.

3. Verify: Check the rendered HTML in your browser’s inspector to confirm the SVG appears with applied classes.

Where to Look First

• Zondicon SVG Directory: Browse available icons (e.g., cloud.svg, cog.svg) to identify names for Blade components.
• Blade Icons Documentation: Understand underlying features like caching, which Blade Zondicons inherits.

Implementation Patterns

Core Workflows

1. Basic Icon Rendering:

   <!-- Static icon with Tailwind classes -->
   <x-zondicon-home class="w-6 h-6" />
   
   <!-- Dynamic icon (e.g., in a loop) -->
   @foreach($icons as $icon)
       <x-zondicon-{{ $icon }} class="w-4 h-4" />
   @endforeach
   

2. Customization via Attributes:

   <!-- Inline styles -->
   <x-zondicon-search style="color: #6b7280; width: 20px; height: 20px;" />
   
   <!-- Data attributes for JS interactivity -->
   <x-zondicon-bell data-tooltip="Notifications" class="w-5 h-5" />
   

3. Global Configuration (Publish Config):

   php artisan vendor:publish --tag=blade-zondicons-config
   

   Configure defaults in config/blade-zondicons.php:

   'default_classes' => 'w-5 h-5 text-gray-500',
   'default_attributes' => ['aria-hidden' => 'true'],
   

   Now all icons inherit these unless overridden:

   <x-zondicon-cloud /> <!-- Uses defaults -->
   <x-zondicon-cloud class="text-red-500" /> <!-- Overrides color -->
   

4. Raw SVG Assets (Publish Assets):

   php artisan vendor:publish --tag=blade-zondicons --force
   

   Use SVGs directly in views or assets:

   <img src="{{ asset('vendor/blade-zondicons/cloud.svg') }}" alt="Cloud" width="24" height="24" />
   

Integration Tips

• Tailwind CSS: Use Tailwind’s arbitrary values for dynamic sizing:

  <x-zondicon-settings class="w-[1.25rem] h-[1.25rem]" />
  

• Dark Mode: Leverage Tailwind’s dark variants:

  <x-zondicon-moon class="dark:text-yellow-300" />
  

• Icon Caching: Enable Blade Icons caching for performance:

  php artisan config:cache
  php artisan view:cache
  

• Livewire/Alpine.js: Bind icons to dynamic states:

  <x-zondicon-x
      class="w-5 h-5 {{ $isActive ? 'text-green-500' : 'text-gray-400' }}"
      wire:click="toggleActive"
  />
  

Gotchas and Tips

Pitfalls

1. Icon Naming Conflicts:

   • Zondicons use hyphenated names (e.g., zondicon-cloud), but Blade components omit the prefix.
   • Fix: Always use x-zondicon- prefix in Blade (e.g., <x-zondicon-cloud/>), not <zondicon-cloud/>.
   • Debug: Check resources/views/vendor/blade-zondicons for compiled components if icons fail to render.

2. Caching Issues:

   • Blade component caching may cause stale icons after updates.
   • Fix: Clear caches after package updates:

     php artisan view:clear
     php artisan config:clear
     

3. SVG Asset Paths:

   • Published SVGs are placed in public/vendor/blade-zondicons/.
   • Gotcha: Forgetting --force flag during publish may overwrite existing files.
   • Tip: Use asset('vendor/blade-zondicons/...') in Blade, not relative paths.

4. Laravel Version Mismatches:

   • The package drops support for Laravel <11. Ensure your composer.json aligns:

     "require": {
         "laravel/framework": "^11.0 || ^12.0"
     }
     

Debugging

• Missing Icons:

  • Verify the icon exists in resources/svg.
  • Check for typos in Blade component names (case-sensitive).
  • Run php artisan view:clear if icons disappear after updates.

• Styling Not Applying:

  • Ensure Tailwind/your CSS framework is processing the classes.
  • Inspect the rendered SVG in browser dev tools to confirm class attributes.

Extension Points

1. Custom Icons:

   • Add your own SVGs to resources/svg and register them in config/blade-zondicons.php:

     'icons' => [
         'custom-icon' => 'path/to/custom.svg',
     ],
     

   • Use in Blade: <x-zondicon-custom-icon />.

2. Dynamic Icon Selection:

   • Create a Blade component to map dynamic data to icons:

     @component('zondicon-'.$iconName, ['class' => 'w-5 h-5'])
     @endcomponent
     

3. Icon Sets:

   • Combine with other Blade Icons packages (e.g., blade-heroicons) for hybrid icon systems:

     @if($useZondicon)
         <x-zondicon-home />
     @else
         <x-heroicon-home />
     @endif
     

Performance Tips

• Precompile Icons: Use Blade Icons’ caching to reduce runtime SVG parsing:

  php artisan blade-icons:cache
  

• Lazy-Load Non-Critical Icons: Load icons dynamically via JavaScript for off-screen elements:

  if ('IntersectionObserver' in window) {
      const observer = new IntersectionObserver((entries) => {
          entries.forEach(entry => {
              if (entry.isIntersecting) {
                  const icon = entry.target;
                  icon.innerHTML = icon.dataset.icon;
                  observer.unobserve(icon);
              }
          });
      });
      document.querySelectorAll('[data-icon]').forEach(el => observer.observe(el));
  }
  

  <span data-icon="<x-zondicon-cloud class='w-5 h-5' />"></span>
  

Configuration Quirks

• Default Attributes: The default_attributes config key accepts an array of attributes to apply to all icons:

  'default_attributes' => [
      'aria-hidden' => 'true',
      'focusable' => 'false',
  ],
  

  Note: Inline styles or classes override these.

• Icon Size Limits: Zondicons are designed for small-to-medium sizes (typically <50px). For larger icons, consider scaling via CSS transforms:

  <x-zondicon-rocket class="scale-150" />