Blade Tabler Icons Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require secondnetwork/blade-tabler-icons
   

   No additional configuration is required—just autoload.

2. First Use Case Render a basic icon in a Blade template:

   <x-tabler-icon name="home" />
   

   Outputs:

   <svg xmlns="http://www.w3.org/2000/svg" ...><path d="M10.293 13.293a1 1 0 0 1 1.414 0l3-3a1 1 0 0 1 1.414 1.414l-3 3a1 1 0 0 1-1.414 0zm7-13a1 1 0 0 1 1.414 0l3 3a1 1 0 0 1-1.414 1.414l-3-3a1 1 0 0 1 0-1.414zM12 18a1 1 0 0 1-1-1V5a1 1 0 0 1 2 0v12a1 1 0 0 1-1 1zm-2-4a2 2 0 1 1 0-4 2 2 0 0 1 0 4zm0-6a4 4 0 1 0 0-8 4 4 0 0 0 0 8z"/></svg>
   

3. Where to Look First

   • Tabler Icons Documentation (for icon names).
   • Package source: src/TablerIcon.php (for customization hooks).

Implementation Patterns

Common Workflows

1. Dynamic Icons via Variables

   <x-tabler-icon :name="$dynamicIconName" class="text-blue-500" />
   

   Pass variables directly from controllers or components.

2. Component Slots for Customization

   <x-tabler-icon name="settings" class="w-6 h-6">
       <title>User Settings</title>
   </x-tabler-icon>
   

   Extend with additional attributes or markup.

3. Integration with Tailwind CSS

   <x-tabler-icon name="brand-github" class="w-8 h-8 fill-current text-gray-800" />
   

   Leverage Tailwind’s utility classes for styling.

4. Reusable Icon Groups Create a Blade component for consistent icon usage:

   <!-- resources/views/components/IconButton.blade.php -->
   <button class="p-2 rounded hover:bg-gray-100">
       <x-tabler-icon :name="$icon" class="w-5 h-5" />
   </button>
   

   Usage:

   <x-icon-button icon="mail" />
   

5. Conditional Icons

   <x-tabler-icon name="{{ $isActive ? 'check' : 'x' }}" />
   

   Dynamically switch icons based on logic.

Integration Tips

• Laravel Mix/PurgeCSS Ensure SVG paths are not purged by adding them to tailwind.config.js:

  module.exports = {
      safelist: [
          /tabler-.*/,
          /fill-current/,
      ],
  };
  

• Dark Mode Support Use dark: variants with Tailwind:

  <x-tabler-icon name="moon" class="dark:text-gray-300" />
  

• Accessibility Add aria-hidden="true" or descriptive <title> tags:

  <x-tabler-icon name="alert-circle" aria-hidden="true" />
  

Gotchas and Tips

Pitfalls

1. Icon Name Mismatches

   • Issue: x-tabler-icon name="homee" (typo) renders nothing.
   • Fix: Validate names against Tabler’s official list. Use IDE autocompletion or a helper:

     // app/Helpers/TablerIcons.php
     public static function validIcons(): array {
         return ['home', 'settings', 'mail', /* ... */];
     }
     

2. SVG Overrides

   • Issue: Custom SVG attributes (e.g., viewBox) may conflict with the component’s defaults.
   • Fix: Extend the component:

     <x-tabler-icon name="custom-svg" viewBox="0 0 24 24" />
     

     Or override in app/Providers/AppServiceProvider.php:

     use SecondNetwork\BladeTablerIcons\TablerIcon;
     
     TablerIcon::macro('customViewBox', function () {
         return '0 0 20 20';
     });
     

3. Caching Headaches

   • Issue: Blade cache may retain old icon names if the component is modified.
   • Fix: Clear cache after updates:

     php artisan view:clear
     

4. Size Consistency

   • Issue: Icons appear inconsistent due to missing width/height.
   • Fix: Default to class="w-4 h-4" in a layout component or use a CSS reset:

     .tabler-icon {
         width: 1em;
         height: 1em;
     }
     

Debugging

• Inspect Rendered SVG Use browser dev tools to verify the <svg> output matches expectations. Common issues:

  • Missing fill attribute → icons appear invisible.
  • Incorrect viewBox → distorted icons.

• Log Icon Names Debug dynamic icons with:

  @php
      \Log::debug('Icon name:', ['name' => $iconName]);
  @endphp
  <x-tabler-icon name="{{ $iconName }}" />
  

Extension Points

1. Custom Icon Sets Override the default SVG source by publishing the config:

   php artisan vendor:publish --provider="SecondNetwork\BladeTablerIcons\TablerIconsServiceProvider"
   

   Modify config/blade-tabler-icons.php to point to a custom SVG directory.

2. Add Interactivity Combine with Alpine.js for dynamic behavior:

   <div x-data="{ open: false }">
       <button @click="open = !open">
           <x-tabler-icon :name="open ? 'chevron-up' : 'chevron-down'" />
       </button>
   </div>
   

3. Server-Side Icon Processing Use the underlying TablerIcon class in PHP:

   use SecondNetwork\BladeTablerIcons\TablerIcon;
   
   $svg = TablerIcon::make('brand-github')->toSvg();
   

4. Localization Override icon names per locale by extending the component:

   <x-tabler-icon name="{{ trans('icons.settings') }}" />