Laravel Mapcn
Toggle sidebar

Advanced Usage

Docs / Advanced

Livewire Interactivity

The package dispatches events to Livewire and listens for specific commands. This allows you to interact with the map from your PHP component seamlessly.

Events Dispatched to Livewire

Listen for these events in your Livewire component:

EventPayloadDescription
map:loaded—Map style is fully loaded
map:clicklat, lng, detailUser clicked on the map
map:zoom-changedzoomZoom level changed
map:center-changedlat, lngMap center changed
map:marker-clickedid, lat, lngA marker was clicked
map:marker-drag-endid, lat, lngA draggable marker was released

Commands from Livewire

Trigger these from your Livewire component using $this->dispatch():

CommandDescription
map:fly-toMove the map smoothly to a new location
map:set-zoomChange zoom level
map:fit-boundsFit the map view to specific coordinates
map:resizeForce a map recalculation (useful for show/hide containers)

Example: Fly To Location

Smoothly animate the map to a new location from your Livewire component:

php — Livewire Component 
use Livewire\Component;

class FlightTracker extends Component
{
    public function centerOnPilot()
    {
        $this->dispatch('map:fly-to', [
            'center' => [-0.09, 51.5],
            'zoom' => 12,
            'essential' => true,
        ]);
    }

    public function render()
    {
        return view('livewire.flight-tracker');
    }
}
blade — flight-tracker.blade.php 
<div>
    <button wire:click="centerOnPilot">
        Center on Pilot
    </button>

    <x-map
        :center="[-0.09, 51.5]"
        :zoom="8"
        height="400px"
    >
        <x-map-controls />
    </x-map>
</div>

Theme Awareness

By default the map follows the .dark class on your <html> element when theme="auto" is set. You can also force a specific theme:

theme="light"

theme="dark"

Controlled Viewport

Track and control the map viewport (center, zoom, bearing, pitch) by listening to events and using Alpine.js for real-time reactivity.

lng: lat: zoom: bearing: ° pitch: °

Viewport Event Reference

EventDetailDescription
map:movelat, lngFired continuously as the map moves
map:center-changedlat, lngFired once movement ends
map:zoomzoomFired continuously during zoom
map:zoom-changedzoomFired once zoom ends
map:bearing-changedbearingFired when the map is rotated
map:pitch-changedpitchFired when the map is tilted

Example: Fit Bounds

Automatically fit the map to show all your markers:

php — Livewire Component 
public function showAllLocations()
{
    $this->dispatch('map:fit-bounds', [
        'bounds' => [
            [-0.15, 51.49],  // Southwest corner [lng, lat]
            [-0.01, 51.54],  // Northeast corner [lng, lat]
        ],
        'padding' => 50,
    ]);
}

Example: Set Zoom

Programmatically change the zoom level:

php — Livewire Component 
public function zoomIn()
{
    $this->dispatch('map:set-zoom', [
        'zoom' => 16,
    ]);
}

Example: Resize

Force the map to recalculate its size when the container changes (e.g. tabs, accordions, modals):

php — Livewire Component 
public function onTabChanged()
{
    $this->dispatch('map:resize');
}
The map:resize dispatch is essential when the map is inside a container that was hidden on page load (e.g., an inactive tab or collapsed accordion). MapLibre needs a resize event to calculate tile positions correctly.

Performance Tips

Use Clusters for Large Datasets

Always use <x-map-cluster-layer> instead of individual markers when rendering more than ~50 points.

Limit Zoom Range

Set :min-zoom and :max-zoom to constrain tile loading and reduce network requests.

Lazy Load Maps

For pages with multiple maps, consider loading maps only when they scroll into view using Livewire's lazy loading.

CDN vs Local Assets

Set load_from_cdn to false in config to serve MapLibre assets from your own server for offline or intranet use.

Previous ← Clusters