Twig Bootstrap Icons Laravel Package

Getting Started

Minimal Setup

1. Install the package:

   composer require whatwedo/twig-bootstrap-icons
   

2. Register the Twig extension in your app/Twig/AppExtension.php (or equivalent):

   use whatwedo\TwigBootstrapIcons\BootstrapIconsExtension;
   
   public function getExtensions(): array
   {
       return [
           new BootstrapIconsExtension(),
       ];
   }
   

   For Symfony, add to bundles.php:

   whatwedo\TwigBootstrapIcons\whatwedoTwigBootstrapIconsBundle::class => ['all' => true],
   

3. First use case: Render an icon in a Twig template:

   {{ bootstrap_icon('house') }}
   

Implementation Patterns

Core Usage Patterns

• Basic icon rendering:

  {{ bootstrap_icon('gear') }}
  

  Outputs the SVG for the gear icon (e.g., <svg>...</svg>).

• Dynamic icons with variables:

  {% set icon = 'bell' %}
  {{ bootstrap_icon(icon) }}
  

• Custom attributes:

  {{ bootstrap_icon('person', {
      class: 'text-blue-500 h-8 w-8',
      'aria-hidden': 'true',
      title: 'User Profile'
  }) }}
  

• Conditional icons:

  {% if is_admin %}
      {{ bootstrap_icon('shield-check') }}
  {% else %}
      {{ bootstrap_icon('person') }}
  {% endif %}
  

Integration Tips

1. Pair with Tailwind CSS: Use the class attribute to leverage Tailwind’s utility classes for styling:

   {{ bootstrap_icon('search', { class: 'text-gray-400 hover:text-gray-600' }) }}
   

2. Icon sets and themes: Bootstrap Icons supports filled/variants. Extend the package by overriding the getIcon() method in a custom extension:

   class CustomBootstrapIconsExtension extends BootstrapIconsExtension
   {
       protected function getIcon(string $name): string
       {
           return str_replace('fill-', '', parent::getIcon($name));
       }
   }
   

3. Reusable components: Create a Twig macro for consistent icon usage:

   {% macro icon(name, classes = '') %}
       {{ bootstrap_icon(name, { class: 'h-6 w-6 ' ~ classes }) }}
   {% endmacro %}
   

   Usage:

   {{ _self.icon('envelope', 'text-red-500') }}
   

4. Accessibility: Always include aria-hidden="true" for decorative icons or provide alt text for functional icons:

   {{ bootstrap_icon('exclamation-triangle', {
       class: 'h-5 w-5',
       'aria-hidden': 'true'
   }) }}
   

Gotchas and Tips

Pitfalls

1. Icon name mismatches: Bootstrap Icons uses kebab-case (e.g., house-door). Verify names via the official list. Debug: Check the rendered SVG source or use {{ dump(bootstrap_icon('invalid-icon')) }} to see errors.

2. Caching issues: If icons fail to render after updates, clear Twig cache:

   php artisan cache:clear
   php artisan view:clear
   

3. SVG attribute conflicts: Avoid overriding critical attributes like viewBox or xmlns. Use class for styling instead.

4. Symfony autowiring: If using Symfony, ensure the bundle is properly autowired. Add this to config/packages/twig.php if needed:

   twig:
       extensions:
           - whatwedo\TwigBootstrapIcons\BootstrapIconsExtension
   

Debugging Tips

• Inspect rendered SVG: Use browser dev tools to verify the output matches expectations. Example:

  {{ bootstrap_icon('git')|raw }}
  

  (Use |raw to avoid Twig auto-escaping.)

• Check for updates: The package hasn’t been updated since 2021. Fork and extend if missing features (e.g., Bootstrap Icons 1.10+ support).

• Custom icon paths: Override the default icon path in a custom extension:

  class CustomBootstrapIconsExtension extends BootstrapIconsExtension
  {
      public function __construct()
      {
          $this->iconPath = '/custom/path/to/bootstrap-icons';
      }
  }
  

Extension Points

1. Add custom icons: Extend the getIcon() method to include private icons:

   protected function getIcon(string $name): string
   {
       $customIcons = ['my-icon' => 'custom-svg-content'];
       return $customIcons[$name] ?? parent::getIcon($name);
   }
   

2. Modify SVG output: Filter the SVG before rendering by overriding renderIcon():

   public function renderIcon(string $name, array $attributes = []): string
   {
       $svg = parent::renderIcon($name, $attributes);
       return str_replace('<svg', '<svg data-icon', $svg);
   }
   

3. Lazy-load icons: For performance, dynamically load icons via JavaScript and replace placeholders. Example:

   <span class="icon-placeholder" data-icon="cloud"></span>
   

   Then use a JS library like bootstrap-icons.js.