Advanced Usage

Reactivity

Everything inside <x-map> reacts to your Livewire state. The map element uses wire:ignore.self and only the canvas MapLibre draws into is wire:ignored. When your component re-renders, Livewire morphs the child markers, routes, arcs, GeoJSON and cluster layers in place. They are added, updated or removed on the live map, and the camera stays where the user left it.

Three rules keep updates smooth:

• Don't wrap the map in wire:ignore. Older versions needed it, but now it stops children from updating.
• Give the map a stable id. A user-supplied id is rendered on the element and Livewire keys the morph on it. It is also the mapId you use to target the map.
• Use wire:key (and a stable id) on items rendered in @foreach loops so each item keeps its identity when the array changes.

use Livewire\Component;

class StoreLocator extends Component
{
    public array $stores = [
        ['id' => 1, 'name' => 'Soho', 'lat' => 51.513, 'lng' => -0.136],
        ['id' => 2, 'name' => 'Shoreditch', 'lat' => 51.526, 'lng' => -0.078],
    ];

    public function addStore(float $lat, float $lng): void
    {
        $this->stores[] = [
            'id' => uniqid(),
            'name' => 'New store',
            'lat' => $lat,
            'lng' => $lng,
        ];
    }

    public function removeLast(): void
    {
        array_pop($this->stores);
    }
}

<div>
    <button wire:click="removeLast">Remove last store</button>

    <!-- No wire:ignore: the markers below update in place -->
    <x-map id="stores-map" :center="[-0.1, 51.515]" :zoom="12" height="400px">
        @foreach ($stores as $store)
            <x-map-marker
                wire:key="store-{{ $store['id'] }}"
                :id="'store-'.$store['id']"
                :lat="$store['lat']"
                :lng="$store['lng']"
            >
                <x-marker-tooltip :text="$store['name']" />
            </x-map-marker>
        @endforeach
    </x-map>
</div>

Livewire Interactivity

The package dispatches events to Livewire and listens for specific commands, so you can drive the map from your PHP component.

Events Dispatched to Livewire

Each event is dispatched once as a bubbling DOM CustomEvent that Livewire also receives. That means Alpine (@map:click) and Livewire (#[On('map:click')]) listeners both get it exactly once. Every payload also includes mapId, the id of the map that fired it.

use Livewire\Attributes\On;

#[On('map:marker-clicked')]
public function markerClicked(string $id, float $lat, float $lng, ?string $mapId = null): void
{
    $this->selectedStore = $id;
}

Map events

Marker & popup events

Route events

Arc, GeoJSON & cluster events

Commands from Livewire

Trigger these from your Livewire component using $this->dispatch(). You can pass the payload as named arguments or as a single array.

Map commands

Each accepts an optional mapId. Without it the command applies to every map on the page.

Component commands

These target a component by the id you gave it, so give dynamic routes, arcs, GeoJSON and cluster layers an explicit id.

Targeting a Map

When a page has more than one map, pass mapId with a command to control only that map. Map commands without mapId apply to every map on the page. Outbound events carry the same mapId, so a listener can tell which map fired them.

use Livewire\Attributes\On;

public function showLondon(): void
{
    // Only the map with id="main-map" moves
    $this->dispatch('map:fly-to', mapId: 'main-map', center: [-0.09, 51.5], zoom: 12);
}

#[On('map:click')]
public function mapClicked(float $lat, float $lng, ?string $mapId = null): void
{
    if ($mapId !== 'main-map') {
        return; // ignore clicks on the overview map
    }

    $this->addStore($lat, $lng);
}

<x-map id="main-map" height="400px" />
<x-map id="overview-map" height="200px" :interactive="false" />

Example: Fly To Location

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

use Livewire\Component;

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

    public function render()
    {
        return view('livewire.flight-tracker');
    }
}

<div>
    <button wire:click="centerOnPilot">
        Center on Pilot
    </button>

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

Theme Awareness

With theme="auto" (the default) the map follows a dark/light class or data-theme attribute on your <html> element, and fires map:theme-changed when it switches. You can also force a specific theme, or change it at runtime with the map:set-theme command:

<!-- Force light theme -->
<x-map theme="light" />

<!-- Force dark theme -->
<x-map theme="dark" />

<!-- Auto-detect (default) — follows .dark on <html> -->
<x-map theme="auto" />

Controlled Viewport

Track and control the map viewport (center, zoom, bearing, pitch) by listening to events and using Alpine.js for real-time reactivity. To sync the camera to Livewire, listen to map:viewport-changed. It fires once per movement with the full camera state, so it doesn't flood the server.

<div x-data="{
    viewport: {
        lat: 40.7128,
        lng: -74.006,
        zoom: 8,
        bearing: 0,
        pitch: 0
    }
}">

    <x-map
        :center="[-74.006, 40.7128]"
        :zoom="8"
        @map:move="viewport.lat = $event.detail.lat;
                   viewport.lng = $event.detail.lng"
        @map:zoom="viewport.zoom = $event.detail.zoom"
        @map:bearing-changed="viewport.bearing = $event.detail.bearing"
        @map:pitch-changed="viewport.pitch = $event.detail.pitch"
    />

    <!-- Reactive viewport display -->
    <div class="overlay">
        <span x-text="viewport.lng.toFixed(3)"></span>
        <span x-text="viewport.lat.toFixed(3)"></span>
        <span x-text="viewport.zoom.toFixed(1)"></span>
    </div>
</div>

#[On('map:viewport-changed')]
public function viewportChanged(array $center, float $zoom, float $bearing, float $pitch): void
{
    [$this->lng, $this->lat] = $center;
    $this->zoom = $zoom;
}

Viewport Event Reference

Example: Fit Bounds

Fit the map to show all your markers. padding defaults to 40, and any other MapLibre fitBounds option (e.g. maxZoom, duration) is passed through:

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:

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

Example: Resize

The map resizes itself when its own element changes size. If its container was hidden when the page loaded (tabs, accordions, modals), force a recalculation once it's visible:

public function onTabChanged()
{
    $this->dispatch('map:resize');
}

The $map Magic

Inside any markup in an <x-map>, the Alpine magic $map returns the MapLibre Map instance of the nearest enclosing map. That gives you the full MapLibre API from a button, with no JavaScript file and no server round-trip. It pairs well with <x-map-control> for custom buttons. $map is null until the map has been created.

<x-map :center="[-73.9857, 40.7484]" :zoom="14" provider="openfreemap-liberty">
    <x-map-control position="top-left">
        <button x-on:click="$map.easeTo({ pitch: 60, bearing: -20, duration: 1000 })">3D</button>
        <button x-on:click="$map.easeTo({ pitch: 0, bearing: 0, duration: 1000 })">2D</button>
    </x-map-control>
</x-map>

JavaScript API

For code outside the map markup (your own scripts, other Alpine components), the package exposes window.LivewireMap:

Route controller

// Run code once the map is ready (also after wire:navigate)
LivewireMap.waitForMap('main-map', (map) => {
    map.addControl(new maplibregl.AttributionControl({ compact: true }));
});

// Move a delivery along its route
const route = LivewireMap.getRoute('delivery');
route?.setProgress(0.75, 1500);
const [lng, lat] = route?.pointAt('progress') ?? [];

Alpine.js Directives

x-map-resize resizes the enclosing map whenever its expression becomes truthy. It's useful for maps in tabs, modals and accordions that toggle on the client. For other camera actions use $map (see above).

<div x-data="{ open: false }">
    <button x-on:click="open = !open">Toggle map</button>

    <div x-show="open">
        <x-map height="300px">
            <div x-map-resize="open"></div>
        </x-map>
    </div>
</div>

Custom MapLibre Events

Forward any other MapLibre event as map:{event}. Set it for all maps with the custom_events config key, or per map with the :events prop (the two are merged):

'custom_events' => ['idle', 'sourcedata'],

<x-map :events="['idle', 'rotatestart']" @map:idle="console.log('map is idle')" />

GeoJSON Helper

The package includes a support class that converts PHP arrays (items with lat/lng keys, or GeoJSON Features) into a GeoJSON FeatureCollection:

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