Bootstrap Icons Laravel Package

Getting Started

Minimal Setup in Laravel

1. Install via npm (recommended for Laravel projects using Vite/Webpack):

   npm install bootstrap-icons
   

   Add to your resources/js/app.js or resources/css/app.scss:

   import 'bootstrap-icons/font/bootstrap-icons.css';
   

   Or in app.scss:

   @import "bootstrap-icons/font/bootstrap-icons";
   

2. CDN Alternative (quickest for testing): Add to resources/views/layouts/app.blade.php:

   <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.min.css">
   

3. First Use Case:

   <!-- Blade template -->
   <i class="bi bi-heart-fill text-danger"></i>
   

   Or inline SVG:

   <svg class="bi" width="16" height="16" fill="currentColor">
     <use xlink:href="#heart-fill"/>
   </svg>
   

Key Files to Reference

• Icon Explorer: https://icons.getbootstrap.com/
• SVG Sprite: node_modules/bootstrap-icons/bootstrap-icons.svg
• Font Files: node_modules/bootstrap-icons/font/fonts/

Implementation Patterns

1. Icon Font Integration (Most Common)

Workflow:

1. Installation:

   npm install bootstrap-icons --save-dev
   

2. Configuration (for Laravel Mix/Vite):

   // vite.config.js
   export default defineConfig({
     resolve: {
       alias: {
         '@icons': path.resolve(__dirname, 'node_modules/bootstrap-icons'),
       },
     },
   });
   

3. Usage in Blade:

   <button class="btn btn-outline-primary">
     <i class="bi bi-cloud-upload"></i> Upload
   </button>
   

   Dynamic Icons (Laravel + Blade):

   <i class="bi bi-{{ $iconName }}"></i>
   

2. SVG Sprite Optimization

Pattern: Use the sprite for performance (single HTTP request).

1. Link the Sprite (in app.blade.php):

   <svg style="display: none;">
     <use xlink:href="#heart-fill"/>
   </svg>
   

2. Reference Icons:

   <svg class="bi" width="1em" height="1em" viewBox="0 0 16 16">
     <use xlink:href="#heart-fill"/>
   </svg>
   

3. Dynamic Sprite Loading (Laravel):

   <svg class="bi" width="1em" height="1em" viewBox="0 0 16 16">
     <use xlink:href="{{ asset('node_modules/bootstrap-icons/bootstrap-icons.svg#'.$dynamicIcon) }}"/>
   </svg>
   

3. Inline SVG with Dynamic Data

Use Case: Icons with dynamic colors/sizes.

@php
  $color = auth()->check() ? 'success' : 'secondary';
  $size = request('size') ?: '16';
@endphp
<svg class="bi text-{{ $color }}" width="{{ $size }}" height="{{ $size }}" fill="currentColor">
  <use xlink:href="#{{ $icon }}"/>
</svg>

4. Sass Integration

For Themed Icons:

// resources/scss/custom.scss
@import "bootstrap-icons/font/bootstrap-icons";

.icon-theme {
  .bi {
    color: $primary;
  }
  .bi-heart {
    color: $danger;
  }
}

5. Accessibility Patterns

Decorative Icons:

<i class="bi bi-search" aria-hidden="true"></i>

Interactive Icons:

<button aria-label="Notifications">
  <i class="bi bi-bell-fill" role="img"></i>
</button>

Gotchas and Tips

1. Cross-Domain SVG <use> Issues

• Problem: Chrome blocks <use> with external sprites (e.g., CDN).
• Fix: Use local sprite or inline SVG:

  <!-- Local sprite (recommended) -->
  <svg class="bi" width="1em" height="1em">
    <use xlink:href="{{ asset('node_modules/bootstrap-icons/bootstrap-icons.svg#icon-name') }}"/>
  </svg>
  

2. Vite/Laravel Mix Path Resolving

• Issue: font-face fails if paths aren’t absolute.
• Solution:

  // vite.config.js
  export default defineConfig({
    assetsInclude: ['**/*.svg'],
    resolve: {
      alias: {
        '@icons': path.resolve(__dirname, 'node_modules/bootstrap-icons'),
      },
    },
  });
  

3. Icon Font Loading Delays

• Problem: FOUC (Flash of Unstyled Content) if fonts load late.
• Fix: Preload the font:

  <link rel="preload" href="{{ asset('node_modules/bootstrap-icons/font/fonts/bootstrap-icons.woff2') }}" as="font" type="font/woff2" crossorigin>
  

4. Dynamic Icon Names

• Pitfall: Typos in icon names break rendering.
• Validation Helper:

  // app/Helpers/IconHelper.php
  public static function isValidIcon(string $name): bool {
    return file_exists(resource_path("node_modules/bootstrap-icons/icons/{$name}.svg"));
  }
  

  Usage:

  @if(IconHelper::isValidIcon($iconName))
    <i class="bi bi-{{ $iconName }}"></i>
  @endif
  

5. SVG Optimization

• Tip: Use svgo to optimize SVGs before committing:

  npx svgo --multipass --config=node_modules/bootstrap-icons/.svgo.config.js icons/*.svg
  

6. Dark Mode Support

• Pattern: Use currentColor + CSS variables:

  .dark-mode {
    .bi {
      color: var(--bs-dark-icon-color);
    }
  }
  

7. Laravel Mix Asset Handling

• Issue: Mix doesn’t copy node_modules by default.
• Fix: Add to webpack.mix.js:

  mix.copy('node_modules/bootstrap-icons', 'public/vendor/bootstrap-icons');
  

8. Icon Search in Laravel

• Use Case: Search icons programmatically.
• Solution:

  // app/Services/IconService.php
  public function getIconList(): array {
    return array_map(
      fn($file) => pathinfo($file, PATHINFO_FILENAME),
      glob(resource_path('node_modules/bootstrap-icons/icons/*.svg'))
    );
  }
  

9. Custom Icon Generation

• Workflow:
  1. Design in Figma (16x16 grid).
  2. Export as SVG (no stroke, fill="currentColor").
  3. Place in resources/svg/custom/ and reference:

     <svg class="bi" width="1em" height="1em" viewBox="0 0 16 16">
       <use xlink:href="{{ asset('svg/custom/your-icon.svg#icon-viewbox') }}"/>
     </svg>
     

10. Debugging Missing Icons

• Steps:
  1. Check the icon exists in node_modules/bootstrap-icons/icons/.
  2. Verify the class name matches (e.g., bi-heart vs bi-heart-fill).
  3. Inspect the <use> href for typos (e.g., #heart-fill vs #heartfill).