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.

Alpine.js Directives

Interact with the map directly from any DOM element using Alpine directives:

DirectiveValueDescription
x-map-fly-tocenter, zoomSmoothly move the map on click
x-map-fit-boundsboundsFit map to coordinates on click
x-map-set-zoomintChange zoom level on click
x-map-resize''Trigger map resize on click

GeoJSON Helper

The package includes a support class to easily convert PHP arrays or models into GeoJSON FeatureCollections:

php 
use Kwasii\LivewireMapcn\Support\GeoJSON;

$data = [
    ['name' => 'London', 'lat' => 51.5, 'lng' => -0.1],
    ['name' => 'Paris', 'lat' => 48.8, 'lng' => 2.3],
];

$geojson = GeoJSON::fromArray($data);
// Returns a valid GeoJSON array structure

Performance Tips

Clustering Precision

Tune :cluster-radius (higher is faster) and :cluster-max-zoom to balance performance and detail.

Simplify Geometry

Increase :tolerance (e.g., 1.0) to simplify GeoJSON geometry or :buffer to reduce off-screen flashing.

Throttled Events

Use Alpine's .throttle or .debounce when listening to continuous events like @map:move.

Dynamic Data

Use the map:update-cluster-data-{id} event for real-time filtering instead of refreshing the whole component.

Previous ← Clusters