Swiper Laravel Package

Getting Started

Minimal Setup

1. Installation

   composer require contao-components/swiper
   

   Ensure swiper is included in your resources/js/app.js (or equivalent):

   import Swiper from 'swiper';
   

2. Basic Usage Add the Swiper CSS and JS to your Laravel Blade template:

   @vite(['resources/css/swiper.css', 'resources/js/app.js'])
   

   Initialize Swiper in a container:

   <div class="swiper">
       <div class="swiper-wrapper">
           <div class="swiper-slide">Slide 1</div>
           <div class="swiper-slide">Slide 2</div>
       </div>
   </div>
   

3. First Use Case Use the Swiper class to initialize a simple slider:

   document.addEventListener('DOMContentLoaded', () => {
       new Swiper('.swiper', {
           loop: true,
           navigation: {
               nextEl: '.swiper-button-next',
               prevEl: '.swiper-button-prev',
           },
       });
   });
   

Implementation Patterns

Common Workflows

1. Dynamic Content Loading Fetch slides via AJAX and update Swiper dynamically:

   const swiper = new Swiper('.swiper');
   fetch('/api/slides')
       .then(response => response.json())
       .then(slides => {
           slides.forEach(slide => {
               const slideEl = document.createElement('div');
               slideEl.className = 'swiper-slide';
               slideEl.innerHTML = slide.content;
               swiper.slides[0].appendChild(slideEl);
               swiper.update();
           });
       });
   

2. Laravel Blade Integration Pass Swiper configuration from Laravel to JavaScript:

   <script>
       const swiperConfig = @json([
           'loop' => true,
           'autoplay' => ['delay' => 3000],
       ]);
   </script>
   

   Use in JS:

   new Swiper('.swiper', swiperConfig);
   

3. Reusable Components Create a Vue/React wrapper for Swiper:

   <template>
       <div class="swiper">
           <div class="swiper-wrapper">
               <div v-for="slide in slides" class="swiper-slide">{{ slide }}</div>
           </div>
       </div>
   </template>
   
   <script>
   import Swiper from 'swiper';
   export default {
       mounted() {
           new Swiper(this.$el.querySelector('.swiper'), {
               slidesPerView: 3,
           });
       },
   };
   </script>
   

Integration Tips

• Laravel Mix/Vite: Ensure Swiper CSS/JS are processed through your build pipeline.
• Tailwind CSS: Use Swiper’s utility classes (e.g., swiper-slide) alongside Tailwind for styling.
• Server-Side Rendering (SSR): Lazy-load Swiper in Vue/React to avoid hydration mismatches.

Gotchas and Tips

Pitfalls

1. Initialization Timing

   • Swiper must be initialized after the DOM is ready. Use DOMContentLoaded or mounted() in frameworks.
   • Avoid initializing Swiper on dynamically added elements without swiper.update().

2. CSS Conflicts

   • Swiper’s default styles may clash with Tailwind/Bootstrap. Override with:

     .swiper-slide {
         @apply block; /* Example Tailwind override */
     }
     

3. Lazy Loading

   • Use lazy: true for performance, but ensure images are preloaded if critical:

     new Swiper('.swiper', {
         lazy: {
             loadOnTransitionStart: true,
             loadPrevNext: true,
         },
     });
     

Debugging

• Console Errors: Check for missing modules (e.g., swiper/pagination):

  import Swiper from 'swiper';
  import 'swiper/modules/pagination'; // Explicitly import modules
  

• Breakpoints: Use swiper.on('breakpoint', () => console.log(swiper)) to debug responsive behavior.

Extension Points

1. Custom Modules Extend Swiper with custom modules:

   const customModule = {
       name: 'custom',
       params: {
           customOption: {
               default: false,
           },
       },
       on: {
           init: function() {
               if (this.params.customOption) {
                   console.log('Custom option enabled!');
               }
           },
       },
   };
   Swiper.use([customModule]);
   

2. Laravel Service Provider Bind Swiper to Laravel’s container for dependency injection:

   // app/Providers/AppServiceProvider.php
   public function register()
   {
       $this->app->singleton(Swiper::class, function() {
           return new Swiper('.swiper', config('swiper.defaults'));
       });
   }
   

3. Configuration Management Centralize Swiper settings in config/swiper.php:

   return [
       'defaults' => [
           'loop' => env('SWIPER_LOOP', false),
           'autoplay' => ['delay' => 3000],
       ],
   ];