Livewire Slide Overs Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require laravelcm/livewire-slide-overs
   

   Ensure your project meets requirements: PHP 8.3+, Laravel 11/12, Livewire 3.4/4.x.

2. Add the Livewire directive to your layout (e.g., resources/views/layouts/app.blade.php):

   @livewire('slide-over-panel')
   

3. Create your first slide-over component:

   php artisan make:livewire ShoppingCart
   

   Extend SlideOverComponent in the generated class:

   use Laravelcm\LivewireSlideOvers\SlideOverComponent;
   
   class ShoppingCart extends SlideOverComponent
   {
       public function render() { return view('livewire.shopping-cart'); }
   }
   

4. Trigger the slide-over from a Blade view:

   <button wire:click="$dispatch('openPanel', { component: 'shopping-cart' })">
       Open Cart
   </button>
   

First Use Case: Modal-Like Drawer

Replace a traditional modal with a slide-over for a shopping cart or user profile. The package handles animations, stacking, and state management automatically.

Implementation Patterns

1. Component Workflow

• Mounting Data: Pass arguments via $dispatch to mount():

  <button wire:click="$dispatch('openPanel', {
      component: 'edit-user',
      arguments: { userId: {{ $user->id }} }
  })">Edit</button>
  

  public function mount(int $userId) { $this->user = User::find($userId); }
  

• Dynamic Resizing: Adjust width during runtime:

  public function expand() { $this->resizePanel('max-w-5xl'); }
  

• Closing Logic: Use closePanel() with optional events:

  public function save() {
      $this->closePanelWithEvents(['refreshList']);
  }
  

2. Stacked Panels

• Enable stacking in config (config/livewire-slide-over.php):

  'stack' => true,
  

• Nested Triggers: Open panels sequentially:

  <button wire:click="$dispatch('openPanel', { component: 'step-one' })">Step 1</button>
  

  // Inside StepOne component:
  public function proceed() {
      $this->closePanel()->dispatch('openPanel', ['component' => 'step-two']);
  }
  

3. Optimistic UI

• Instant Open: Use $slideOver.open() for immediate feedback:

  <button onclick="$slideOver.open('shopping-cart')">Cart</button>
  

  • Cache resolved attributes in sessionStorage for subsequent opens.

4. Configuration Overrides

• Per-Component Settings: Override defaults in your component:

  public static function panelMaxWidth(): string { return '3xl'; }
  public static function closePanelOnEscape(): bool { return false; }
  

5. Integration with Livewire Events

• Listen for Panel Events: Use #[On] attributes (Livewire 4+):

  use Laravelcm\LivewireSlideOvers\Events\PanelClosed;
  
  #[On('panel.closed')]
  public function handlePanelClosed(PanelClosed $event) {
      // React to closures
  }
  

Gotchas and Tips

Pitfalls

1. Tailwind CSS Setup:

   • If using Tailwind v4, add @source to your CSS:

     @source "../vendor/laravelcm/livewire-slide-vers/resources/views";
     

   • For v3, update tailwind.config.js:

     content: ['./vendor/laravelcm/livewire-slide-overs/resources/views/**/*.blade.php'],
     

2. Component Naming:

   • Use fully qualified names for nested components (e.g., Shop/Actions/ShoppingCart → 'shop.actions.shopping-cart').
   • Avoid hyphens (-) in component names; use underscores (_) or camelCase.

3. Stacked Panel Quirks:

   • Escape Key: Closes only the active panel by default (configurable via closePanelOnEscapeIsForceful).
   • Overflow: Ensure parent containers have overflow: hidden to prevent stacking artifacts.

4. Dynamic Resizing:

   • Use Tailwind classes (e.g., max-w-2xl) or JIT values (e.g., max-w-[800px]).
   • Resizing is client-side only; no re-render occurs.

5. Model Binding:

   • Type-hint models in mount() for automatic binding:

     public function mount(User $user) { /* ... */ }
     

   • Pass the ID as an argument (not the model instance).

Debugging Tips

1. Check Console for Errors:

   • Look for Uncaught ReferenceError: $slideOver is not defined if JS isn’t loaded. Verify include_js in config.

2. Inspect Panel Attributes:

   • Use browser dev tools to check if sessionStorage caches panel attributes correctly for instant opens.

3. Stacked Panel Debugging:

   • Add x-data to Blade to log panel IDs:

     <div x-data="{ panels: [] }" x-on:openPanel="panels.push($event.detail.component)">
         {{ json_encode($panels) }}
     </div>
     

4. Livewire Event Listeners:

   • Ensure #[On] attributes are used in Livewire 4+. For v3, use registerScript:

     public function mount() {
         $this->registerScript('panelClosed', '$wire.on("panel.closed", () => { /* ... */ })');
     }
     

Extension Points

1. Custom Animations:

   • Override the default slide animation by extending the package’s JS. Publish assets:

     php artisan vendor:publish --tag=livewire-slide-over-assets
     

   • Modify resources/js/slide-over.js.

2. Native Dialog Mode:

   • Enable via config:

     'native_dialog' => true,
     

   • Useful for accessibility compliance (e.g., role="dialog").

3. Custom Panel Attributes:

   • Pass arbitrary classes via $slideOver.open():

     <button onclick="$slideOver.open('panel', {}, { class: 'bg-gray-100' })">Open</button>
     

4. Server-Side Logic:

   • Use #[On] to react to panel events server-side (e.g., update a parent component’s state when a panel closes).

Performance

• Avoid Heavy Data in mount(): Fetch data lazily (e.g., in updated() or after panel opens).
• Cache Panel Attributes: The package caches resolved attributes in sessionStorage for instant opens after the first render.