Blade Zondicons Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require blade-ui-kit/blade-zondicons
   

   • No additional setup required for basic usage.

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

   <x-zondicon-cloud class="w-6 h-6 text-gray-500"/>
   

   • Verify the icon appears with the specified Tailwind classes.

3. Where to Look First:

   • Package README for usage examples.
   • Blade Icons Documentation for advanced features (e.g., caching).
   • /resources/svg directory in the package for the full list of available icons.

Implementation Patterns

Usage Patterns

1. Component-Based Icons:

   • Use self-closing Blade components for icons:

     <x-zondicon-search class="text-blue-500"/>
     

   • Supports all standard Blade component attributes (e.g., class, style, id).

2. Dynamic Icons with Variables:

   • Pass dynamic icon names via Blade variables:

     @php
         $icon = 'bell';
     @endphp
     <x-zondicon-{{ $icon }} class="w-5 h-5"/>
     

3. Consistent Styling with Config:

   • Publish the config file to set default classes/attributes:

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

   • Configure in config/blade-zondicons.php:

     'default_classes' => 'text-gray-600',
     'default_attributes' => ['aria-hidden' => 'true'],
     

4. Raw SVG Assets:

   • Publish SVGs for direct use in assets:

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

   • Reference in views:

     <img src="{{ asset('vendor/blade-zondicons/heart.svg') }}" alt="Heart" width="20" height="20"/>
     

5. Integration with Tailwind CSS:

   • Leverage Tailwind’s utility classes for responsive sizing/colors:

     <x-zondicon-menu class="w-4 h-4 md:w-6 md:h-6 text-indigo-600 hover:text-indigo-800"/>
     

6. Icon Caching:

   • Enable Blade Icons caching for performance:

     // config/blade-icons.php
     'cache' => true,
     

Workflows

1. Design System Integration:

   • Use the package as part of a Laravel design system by:
     • Defining a base icon component in resources/views/components/zondicon.blade.php.
     • Extending with custom variants (e.g., x-zondicon-alert-filled).

2. Admin Panel Development:

   • Rapidly prototype admin UI with icons for actions (e.g., edit, delete):

     <button>
         <x-zondicon-edit class="mr-2"/>
         Edit
     </button>
     

3. Dark Mode Support:

   • Dynamically toggle icon colors via JavaScript:

     document.body.classList.toggle('dark');
     // Icons will inherit Tailwind dark mode classes (e.g., dark:text-white).
     

4. Localization:

   • Use icons in multilingual apps by pairing with localized text:

     <x-zondicon-globe class="mr-2"/>
     {{ __('messages.welcome') }}
     

Integration Tips

1. Laravel Mix/Webpack:

   • Ensure no conflicts with existing SVG handling by excluding the published SVGs from processing if not needed.

2. Inertia.js:

   • Use the same Blade components in Inertia responses:

     // Inertia response
     return response()->inertia('Dashboard', {
         icons: ['dashboard', 'settings'],
     });
     

     <!-- Dashboard.blade.php -->
     <x-zondicon-{{ $icons[0] }} class="w-8 h-8"/>
     

3. Testing:

   • Test icon rendering in PHPUnit:

     public function test_zondicon_component()
     {
         $this->blade('<x-zondicon-cloud/>')
             ->assertSee('<svg');
     }
     

4. Custom Icons:

   • Extend the package by creating custom components in app/View/Components that wrap Zondicons:

     // app/View/Components/CustomZondicon.php
     class CustomZondicon extends Component
     {
         public $name;
         public $classes = '';
     
         public function render()
         {
             return view('components.custom-zondicon', [
                 'name' => $this->name,
                 'classes' => $this->classes,
             ]);
         }
     }
     

     <!-- resources/views/components/custom-zondicon.blade.php -->
     <x-zondicon-{{ $name }} {{ $classes }}/>
     

Gotchas and Tips

Pitfalls

1. Icon Naming Conflicts:

   • Zondicons use hyphenated names (e.g., zondicon-cloud), but Blade components are camelCase by default (x-zondicon-cloud). Stick to the package’s naming convention to avoid errors.

2. Caching Issues:

   • If icons don’t render after publishing config/SVGs, clear Laravel’s view cache:

     php artisan view:clear
     

3. SVG Asset Paths:

   • After publishing SVGs, ensure the public/vendor/blade-zondicons directory exists and is accessible. Misconfigured paths will break <img> references.

4. Blade Component Registration:

   • The package registers components automatically, but if you encounter Class 'Zondicon' not found errors, verify:
     • The package is installed correctly (composer show blade-ui-kit/blade-zondicons).
     • No naming collisions with other Blade components.

5. Dynamic Icon Names:

   • Avoid dynamic icon names that could lead to XSS (e.g., user-provided input). Sanitize or whitelist allowed icons:

     $allowedIcons = ['cloud', 'search', 'bell'];
     if (in_array($userInput, $allowedIcons)) {
         <x-zondicon-{{ $userInput }}/>
     }
     

Debugging

1. Missing Icons:

   • Check the /resources/svg directory in the package for the icon’s SVG file. If missing, ensure you’re using the latest version (composer update blade-ui-kit/blade-zondicons).

2. Styling Not Applying:

   • Verify Tailwind or CSS classes are correctly applied. Use browser dev tools to inspect the rendered <svg> element.

3. Performance Issues:

   • Enable Blade Icons caching ('cache' => true in config/blade-icons.php) to reduce compilation overhead.

4. Configuration Overrides:

   • If default classes/attributes aren’t applying, check for typos in the published config file (config/blade-zondicons.php).

Tips

1. Icon Explorer:

   • Use the Zondicons website to browse and copy icon names directly into your Blade components.

2. Consistent Sizing:

   • Define a base icon size in your config to maintain consistency:

     'default_classes' => 'w-5 h-5',
     

3. Accessibility:

   • Add aria-hidden="true" via config or manually to non-interactive icons:

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

4. Dark Mode:

   • Use Tailwind’s dark mode classes for automatic theme switching:

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

5. Custom Colors:

   • Override colors via inline styles or CSS variables:

     <x-zondicon-heart style="--zondicon-color: #ef4444"/>
     

     (Note: Requires CSS custom properties support in the SVG.)

6. Local Development:

   • For faster iteration, symlink the SVG directory to your project’s public folder:

     ln -s vendor/blade-ui-kit/blade-zondicons/resources/svg public/vendor/blade-zondicons
     

7. Extension Points:

   • Override individual icons by publishing them and replacing the SVGs in public/vendor/blade-zondicons.
   • Create a custom component that extends Zondicon for reusable icon variants.

8. Laravel 12+ Features:

   • Leverage Laravel 12’s stacked components to nest icons with text:

     <x-stack>
         <x-zondicon-alert class="text-red-500"/>
         <span>Notification</span>
     </x-stack>