Livewire Map Component Laravel Package

Getting Started

First Use Case

Display a draggable marker:

<livewire:lbcdev-map
    latitude="40.7128"
    longitude="-74.0060"
    :markers="['40.7128,-74.0060']"
    marker-draggable="true"
/>

Requires v1.0.5+ if the map sits underneath modals/dropdowns in your host app — see Gotchas.

Implementation Patterns

Core Workflows

1. Dynamic Marker Management:

   // In Livewire component
   public $markers = ['40.7128,-74.0060', '34.0522,-118.2437'];
   
   public function addMarker($lat, $lng) {
       $this->markers[] = "$lat,$lng";
   }
   

   <livewire:lbcdev-map
       :markers="$markers"
       @marker-added="addMarker"
   />
   

2. Event-Driven Integration:

   • Map Click: @map-clicked="handleMapClick($event)"
   • Marker Drag: @marker-dragged="updateMarker($event)"

   public function handleMapClick($event) {
       $this->addMarker($event['lat'], $event['lng']);
   }
   

3. Theme Switching:

   <livewire:lbcdev-map
       :darkMode="app()->isDarkModeEnabled()"
   />
   

Integration Tips

• Inside Modals / Slide-overs: Since v1.0.5 the map root uses a CSS isolation: isolate stacking context, so it no longer paints over host-app modals. If a map is the modal body, keep the modal content scrollable with a fixed map height (class="h-64" or a wrapper with height), otherwise Leaflet renders 0px tall inside a collapsed container. Call map.invalidateSize() after the modal opens if tiles look off-center.

• Form Submission: Bind marker data to a model:

  public $location;
  public function updatedMarkers() {
      $this->location = implode(',', $this->markers);
  }
  

  <input wire:model="location" type="hidden">
  

• Custom Styling: Publish views (php artisan vendor:publish --tag=lbcdev-map-views) and override:

  @push('leaflet-styles')
      .leaflet-container { border-radius: 8px; }
  @endpush
  

• Server-Side Validation:

  protected $rules = [
      'markers' => 'required|array',
      'markers.*' => 'regex:/^\d+\.\d+,\s*-\d+\.\d+$/'
  ];
  

Gotchas and Tips

Common Pitfalls

1. Missing Leaflet Dependencies:

   • Symptom: Blank map or JS errors.
   • Fix: Ensure Leaflet CSS/JS are loaded before @livewireStyles.

2. Marker Coordinates Format:

   • Issue: markers prop expects strings like "40.7128,-74.0060" (not arrays/objects).
   • Fix: Use implode(',', [$lat, $lng]) when passing PHP arrays.

3. Event Payload Mismatch:

   • Problem: @marker-dragged emits {lat, lng, id}, but your handler expects {lat, lng}.
   • Solution: Update handler to destructure:

     public function updateMarker($event) {
         $this->markers[$event['id']] = "$event['lat'],$event['lng']";
     }
     

4. Read-Only Mode Quirks:

   • Gotcha: Disables all interactions (clicks, drags). Use sparingly for forms.

5. Stacking Context / Overlay Overlap (v1.0.5):

   • What changed: The map container now declares isolation: isolate, creating its own stacking context. Leaflet's internal panes/controls (z-index 400–1000) no longer escape and cover your app's modals, dropdowns, toasts, or sticky headers.
   • What to do: Remove existing z-index hacks (e.g. z-index: 9999 on modal wrappers, z-index: 0 on the map, !important overrides). They are no longer needed and can now fight the new isolation context.
   • If you override map styles: Re-publish/merge the views (vendor:publish --tag=lbcdev-map-views --force) so your published copy contains the isolation rule; stale published views keep the old bug. Then php artisan view:clear.
   • If you intentionally layered custom HTML over the map: Because the map no longer leaks z-index, an overlay placed outside the component with a low z-index can now be hidden behind it. Either move the overlay inside the published map view or give it an explicit z-index within the parent stacking context.

Debugging Tips

• Inspect Events:

  @this.on('marker-dragged', function(event) {
      console.log('Event:', event);
  })
  

• Overlay Still Covered?: Check the computed z-index of the map's ancestors — a parent with transform, filter, opacity < 1, or its own z-index creates a new stacking context and re-introduces the problem regardless of the package fix. Move the map wrapper out of such a parent or raise the modal's stacking context.

• Check Published Views: If customizations disappear after vendor:publish, clear cached views:

  php artisan view:clear
  

Extension Points

1. Custom Layers: Override the mountMap method in your Livewire component:

   public function mountMap() {
       $this->map->addLayer(LbcdevMap::tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png'));
   }
   

2. Geocoding: Integrate with a service (e.g., Nominatim) via @map-clicked:

   public function handleMapClick($event) {
       $address = $this->geocode($event['lat'], $event['lng']);
       $this->address = $address;
   }
   

3. Performance:

   • For >50 markers, use marker-cluster-group:

     public function mountMap() {
         $this->map->addLayer(LbcdevMap::markerClusterGroup($this->markers));
     }
     

   • Lazy-load markers via @map-view event.
   • Mounting many maps inside modals? Reuse a single component instance and call invalidateSize() on open instead of re-rendering.