API Reference

Overview

The livewire-mapcn package provides a collection of Blade components for building interactive maps. All components must be nested inside the root <x-map> component. Everything inside the map is reactive: when your Livewire component re-renders, children update in place (use wire:key in loops and never wrap the map in wire:ignore).

Props are listed in kebab-case as you write them in Blade. Prefix a prop with : to pass a PHP expression (arrays, booleans, numbers), e.g. :zoom="12". Coordinates are always [lng, lat] arrays, except the lat/lng props of markers and popups.

Components

<x-map>

The root component. Give it a stable id attribute (used as mapId and for Livewire morphing). Other HTML attributes are rendered on the map element. See the Map page.

<x-map-controls>

Built-in navigation controls. See the Controls page.

<x-map-control>

Places any markup over the map, styled as a control group. Inside it, the Alpine magic $map gives you the MapLibre instance.

<x-map-control position="top-left">
    <button x-on:click="$map.easeTo({ pitch: 60, bearing: -20, duration: 1000 })">3D view</button>
</x-map-control>

<x-map-marker>

Accepts <x-marker-content>, <x-marker-tooltip>, <x-marker-popup> and <x-marker-label> as children. See the Markers page.

<x-marker-content>

Replaces the default dot with your own markup (the slot).

<x-marker-popup>

Popup opened when the marker is clicked; the slot is the content.

<x-marker-tooltip>

Shown on hover.

<x-marker-label>

A permanent text label next to the marker.

<x-map-popup>

A standalone popup at a coordinate; the slot is the content. See the Popups page.

<x-map-route>

A polyline, optionally snapped to real roads. See the Routes page.

<x-map-route-marker>

A marker pinned to a point on its parent <x-map-route>. It follows the route as its coordinates or progress change. It accepts <x-marker-content>, <x-marker-tooltip>, <x-marker-popup> and <x-marker-label>.

<x-map-route id="delivery" :coordinates="$path" :progress="$progress" :progress-duration="800">
    <x-map-route-marker at="start" color="#16a34a" />
    <x-map-route-marker at="progress" :align-to-route="true">
        <x-marker-tooltip text="Courier" />
    </x-map-route-marker>
    <x-map-route-marker at="end" color="#dc2626" />
</x-map-route>

<x-map-route-group>

Several selectable routes; each item of routes has coordinates and optional id and style keys. See the Routes page.

<x-map-route-list>

A panel listing a route's alternatives (with distance and duration) so the user can pick one. See the Routes page.

<x-map-cluster-layer>

Clusters large point datasets. See the Clusters page.

<x-map-arc>

Curved lines between pairs of points. Each datum is ['id' => …, 'from' => [lng, lat], 'to' => [lng, lat], …]. Extra keys become feature properties you can use in paint expressions and in the tooltip/popup slots. See the Arcs page.

<x-map-geojson>

Renders any GeoJSON as fill, outline and circle layers. Pass false to a paint prop to drop that layer. Supports tooltip/popup slots. See the GeoJSON page.

Events

Events are dispatched once as bubbling DOM events that Livewire also receives. Listen with Alpine (@map:click) or Livewire (#[On('map:click')]). Every payload also includes mapId, except map:route-list-selected.

Map events

Marker & popup events

Route events

Arc, GeoJSON & cluster events

Commands

Dispatch these from Livewire with $this->dispatch(), using named arguments or a single array. See Targeting a Map.

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.

Example: Fly To

// In Livewire Component
public function centerOnPilot()
{
    $this->dispatch('map:fly-to',
        mapId: 'main-map', // optional
        center: [-0.09, 51.5],
        zoom: 12,
        essential: true,
    );
}

JavaScript API

More examples on the Advanced page.

Tile Providers

Built-in tile providers you can use with the provider prop:

Configuration

Keys in config/livewire-mapcn.php: