kwasii/livewire-mapcn

Livewire Mapcn

A Laravel Livewire package inspired by mapcn.dev. Easily integrate beautiful, interactive maps into your Laravel applications using MapLibre GL JS and Alpine.js.

Getting Started

livewire-mapcn provides a set of Blade components that wrap MapLibre GL JS functionality in a "Livewire-friendly" way. It supports markers, popups, routes (with OSRM directions, alternatives and route progress), arcs, GeoJSON overlays, route groups, route lists, clustering, a 3D view toggle and custom controls, all responsive, theme-aware and reactive to Livewire state.

Core Concepts

• Declarative Maps: Define your map and its features using expressive Blade tags.
• Livewire Integration: Components inside <x-map> update in place when your Livewire component re-renders (no camera reset), and you can drive the map from PHP with events.
• Theme Support: Built-in support for light, dark, and auto themes (following Tailwind's .dark class).
• Extensibility: Custom providers, MapLibre style JSON support, and custom event forwarding.

Installation

1. Install via Composer

composer require kwasii/livewire-mapcn

2. Publish Configuration and Assets

php artisan vendor:publish --tag="livewire-mapcn-config"
php artisan vendor:publish --tag="livewire-mapcn-assets"

3. Setup Layout

Include the styles and scripts in your root layout (e.g., app.blade.php).

<head>
    <!-- ... -->
    @livewireMapStyles
</head>
<body>
    <!-- ... -->
    @livewireScripts
    @livewireMapScripts
</body>

Requirements: PHP 8.3+, Laravel 11–13, Livewire 3 or 4 (Alpine.js ships with Livewire). Tailwind CSS is not required: the package stylesheet styles every component.

@livewireMapScripts loads MapLibre GL JS v6 from jsDelivr. v6 is published as an ES module only, so it is imported with <script type="module"> and exposed as window.maplibregl. If you bundle MapLibre yourself, set load_from_cdn to false and assign it to window.maplibregl.

Configuration

You can customize the package behavior via config/livewire-mapcn.php.

API Reference

The package provides several Blade components. All components must be nested inside the root <x-map> component.

Table of Contents

• Map (<x-map>)
• Controls (<x-map-controls>)
• Markers (<x-map-marker>)
• Popups (<x-map-popup>)
• Routes (<x-map-route>)
• Route Groups (<x-map-route-group>)
• Route List (<x-map-route-list>)
• Clusters (<x-map-cluster-layer>)
• Arcs (<x-map-arc>)
• GeoJSON (<x-map-geojson>)
• Advanced Usage
• Upgrading from v1

Map (<x-map>)

The base component for any map implementation.

Usage

<x-map
    :center="[-0.09, 51.5]"
    :zoom="13"
    height="500px"
    provider="carto-voyager"
/>

Props

Loading state

Until a map has loaded, a pulsing-dots overlay is shown; it fades out when MapLibre fires load (the map element gets .lm-loaded).

• Custom content: pass a loading slot. Its attributes are added to the overlay.

  <x-map>
      <x-slot:loading class="gap-3">
          <svg class="animate-spin" ...></svg>
          <span>Loading map…</span>
      </x-slot:loading>
  </x-map>
  

• Restyle the default: set --lm-loader-bg, --lm-loader-backdrop, --lm-loader-color, --lm-loader-dot-size or --lm-loader-fade on .lm-map (or any ancestor).

• Disable: :loader="false" on a map, or 'loader' => false in the config to turn it off everywhere (:loader="true" opts back in). A loading slot is always shown.

Controls (<x-map-controls>)

Adds standard interactive controls to the map.

Usage

<x-map :center="[-0.09, 51.5]" :zoom="13">
    <x-map-controls
        :locate="true"
        :fullscreen="true"
        position="top-right"
    />
</x-map>

Props

3D View

Add :three-d="true" (or just three-d) for a toggle that eases the camera to a tilted, rotated view and back. Pair it with a style that has 3D buildings, such as openfreemap-liberty:

<x-map provider="openfreemap-liberty" :center="[-0.1276, 51.5072]" :zoom="15.5" :pitch="55">
    <x-map-controls three-d :locate="false" />
</x-map>

The map dispatches map:3d-toggled with enabled.

Custom Controls (<x-map-control>)

Pin any markup to a corner of the map. Inside it, the Alpine magic $map is the MapLibre instance:

<x-map :center="[-0.1276, 51.5072]" :zoom="15">
    <x-map-control position="top-left">
        <button type="button" x-on:click="$map.easeTo({ pitch: 60, bearing: -20, duration: 1000 })">3D view</button>
        <button type="button" x-on:click="$map.easeTo({ pitch: 0, bearing: 0, duration: 1000 })">Reset</button>
    </x-map-control>
</x-map>

Markers (<x-map-marker>)

Display interactive markers on the map.

Usage

<x-map :center="[-0.09, 51.5]" :zoom="13">
    <x-map-marker :lat="51.5" :lng="-0.09" color="#ef4444">
        <x-marker-label text="London Office" position="top" />
        <x-marker-tooltip text="Hover for details" />
        <x-marker-popup anchor="bottom">
            <h3>Our HQ</h3>
            <p>Visit us anytime!</p>
        </x-marker-popup>
    </x-map-marker>
</x-map>

Custom Marker Content

<x-map-marker :lat="51.5" :lng="-0.09">
    <x-marker-content>
        <div class="p-2 bg-blue-500 rounded-full">
            <svg>...</svg>
        </div>
    </x-marker-content>
</x-map-marker>

Props

Markers rendered from Livewire state update in place. Use wire:key in loops:

<x-map :center="[-1.2, 7.6]" :zoom="6">
    @foreach ($stores as $store)
        <x-map-marker wire:key="store-{{ $store->id }}" :id="(string) $store->id" :lat="$store->lat" :lng="$store->lng" draggable />
    @endforeach
</x-map>

Marker Sub-Components

Markers can be customized using these child components:

<x-marker-content>

Renders custom HTML as the marker icon.

<x-marker-content>
    <img src="https://raw.githubusercontent.com/kwasii1/livewire-mapcn/HEAD/icons/pin.png" class="w-8 h-8" />
</x-marker-content>

<x-marker-label>

Adds a text label near the marker. Styled with a frosted glass effect, subtle border, and automatic dark mode support.

<x-marker-tooltip>

Adds a hover tooltip using MapLibre's Popup. Styled with a dark pill in light mode and a light pill in dark mode for maximum contrast.

<x-marker-popup>

Adds a click-to-open popup.

Popups (<x-map-popup>)

Standalone popups anchored to specific coordinates.

Usage

<x-map :center="[-0.09, 51.5]" :zoom="13">
    <x-map-popup :lat="51.5" :lng="-0.09" :open="true">
        <p>This is a standalone popup.</p>
    </x-map-popup>
</x-map>

Props

Routes (<x-map-route>)

Draw polylines or fetch real driving/walking/cycling directions.

Basic Polyline

<x-map-route :coordinates="$coords" color="#10b981" :width="5" />

Styled Route

<x-map-route
    :coordinates="$coords"
    color="#ef4444"
    :width="5"
    :opacity="0.8"
    :dash-array="[5, 3]"
    line-cap="butt"
    line-join="miter"
    :with-stops="true"
    stop-color="#22c55e"
/>

OSRM Directions with Alternatives

<x-map-route
    :coordinates="$coords"
    :fetch-directions="true"
    directions-profile="driving"
    :animate="true"
    :animate-duration="3000"
    :alternatives="true"
    :max-alternatives="2"
    alternative-color="#94A3B8"
    :alternative-opacity="0.5"
    :alternative-width="3"
/>

Interactive Route

<x-map-route
    :coordinates="$coords"
    :clickable="true"
    active-color="#0F43C4"
    :active-width="6"
    hover-color="#2563EB"
    :active="false"
/>

Props

Route Progress

Show how far along a route something is (a delivery, a trip, a run), and pin markers to the route with <x-map-route-marker>.

Progress usually changes many times a second (sliders, playback, live tracking), so drive it on the client: progress-model names an Alpine property the route follows, with no server request per change. Entangle it (deferred) if your component needs the value; it is sent with the next request:

<div x-data="{ progress: $wire.entangle('progress') }">
<x-map>
    <x-map-route
        id="delivery"
        :coordinates="$stops"
        fetch-directions
        color="#94a3b8"
        :width="5"
        :dash-array="[0.5, 1.5]"
        progress-model="progress"
        progress-color="#2563eb"
        fit-bounds
    >
        <x-map-route-marker at="start" />
        <x-map-route-marker at="end" />
        <x-map-route-marker at="progress" align-to-route>
            <x-marker-content><div class="vehicle">🚚</div></x-marker-content>
            <x-marker-tooltip text="Driver" />
        </x-map-route-marker>
    </x-map-route>
</x-map>

<input type="range" min="0" max="1" step="0.01" x-model.number="progress">
<button type="button" x-on:click="$mapRoute('delivery').setProgress(1, 1500)">Play</button>
</div>

Other ways to set progress:

• :progress="$progress" renders it from the server. Fine for values that change occasionally (e.g. with wire:poll); add :progress-duration to tween. Avoid wire:model.live on a slider, which sends a request per movement.
• $mapRoute('delivery').setProgress(0.75, 1000) from any Alpine expression, or LivewireMap.getRoute('delivery').setProgress(...) from JavaScript.
• From PHP, without re-rendering: $this->dispatch('map:route-progress-delivery', progress: 1, duration: 1500);

Route Markers (<x-map-route-marker>)

Accepts every marker sub-component (<x-marker-content>, <x-marker-label>, <x-marker-tooltip>, <x-marker-popup>).

Dynamic Route Updates

Update a route's coordinates without a full re-render:

// In your Livewire component
$this->dispatch("map:update-route-data-{$routeId}", [
    'coordinates' => $newCoordinates,
]);

Route Groups (<x-map-route-group>)

Render multiple pre-defined routes with click-to-select behavior. Useful for showing several itineraries on the same map.

Usage

// In your Livewire component
public array $routes = [
    [
        'id' => 'route-a',
        'coordinates' => [[-0.12, 51.51], [-0.11, 51.51], [-0.10, 51.50]],
        'color' => '#ef4444',
        'width' => 4,
    ],
    [
        'id' => 'route-b',
        'coordinates' => [[-0.12, 51.51], [-0.115, 51.515], [-0.10, 51.50]],
        'color' => '#3b82f6',
        'width' => 4,
    ],
];

<x-map :center="[-0.11, 51.505]" :zoom="14">
    <x-map-route-group
        :routes="$routes"
        :selected-route="0"
        :fit-bounds="true"
        :clickable="true"
    />
</x-map>

Props

Dynamic Route Group Updates

Update the route group data without a full re-render:

$this->dispatch("map:update-route-group-{$groupId}", [
    'routes' => $updatedRoutes,
    'selectedRoute' => 1,
]);

Events

Route List (<x-map-route-list>)

An overlay UI panel that displays route alternatives with distance, duration, and selection. Pairs with <x-map-route> (with :alternatives="true") or <x-map-route-group>.

Usage

<x-map :center="[-0.11, 51.505]" :zoom="14">
    <x-map-route
        id="my-route"
        :coordinates="$coords"
        :fetch-directions="true"
        :alternatives="true"
    />
    <x-map-route-list
        route-id="my-route"
        position="top-left"
        title="Available Routes"
        :show-distance="true"
        :show-duration="true"
        :show-fastest-badge="true"
        :show-time-diff="true"
    />
</x-map>

Props

Events

Clusters (<x-map-cluster-layer>)

Efficiently handle thousands of markers by clustering them.

Usage

{{-- From an array --}}
<x-map-cluster-layer
    :data="$locations"
    cluster-color="#3b82f6"
    popup-property="name"
/>

{{-- From a GeoJSON URL --}}
<x-map-cluster-layer
    url="https://maplibre.org/maplibre-gl-js/docs/assets/earthquakes.geojson"
    cluster-color="#3b82f6"
    popup-property="mag"
/>

Props

Popup Slot (Recommended)

Use the popup slot for full HTML control over the point popup. Property values are interpolated via {propertyName} placeholders. {lat} and {lng} are available as special tokens.

<x-map-cluster-layer :data="$locations">
    <x-slot:popup>
        <div class="p-3 space-y-1">
            <h3 class="font-semibold text-sm">{name}</h3>
            <p class="text-xs text-gray-500">{address}</p>
            <div class="flex items-center gap-2 text-xs">
                <span>⭐ {rating}</span>
                <span>📞 {phone}</span>
            </div>
            <p class="text-[11px] text-gray-400">{lat}, {lng}</p>
        </div>
    </x-slot:popup>
</x-map-cluster-layer>

Popup Template (Attribute)

Alternatively, pass an HTML string with {property} placeholders as an attribute:

<x-map-cluster-layer
    :data="$locations"
    popup-template='<div class="p-2"><strong>{name}</strong><br>{address}</div>'
/>

Popup Priority

1. <x-slot:popup> — Full slot control with Blade HTML
2. popup-template="..." — Inline HTML attribute with placeholders
3. popup-property="name" — Auto-styled card using one property as title
4. Default — Shows name/title/label (if present) plus lat/lng coordinates

Dynamic Data Updates

To update cluster data without a full re-render, dispatch a Livewire event:

// In your Livewire component
$this->dispatch("map:update-cluster-data-{$clusterId}",
    \Kwasii\LivewireMapcn\Support\GeoJSON::fromArray($filteredData)
);

Arcs (<x-map-arc>)

Curved lines between pairs of points: flight paths, shipping lanes, migration, transfers. Arcs are quadratic Bézier curves and cross the antimeridian the short way. A wider invisible hit layer makes thin arcs easy to hover and click.

public array $flights = [
    ['id' => 'acc-lhr', 'from' => [-0.17, 5.60], 'to' => [-0.45, 51.47], 'city' => 'London', 'mode' => 'air'],
    ['id' => 'tem-rtm', 'from' => [0.02, 5.63], 'to' => [4.00, 51.95], 'city' => 'Rotterdam', 'mode' => 'sea'],
];

<x-map projection="globe" :center="[20, 25]" :zoom="1.2">
    <x-map-arc
        id="flights"
        :data="$flights"
        :curvature="0.25"
        :paint="['line-color' => ['match', ['get', 'mode'], 'air', '#a78bfa', 'sea', '#34d399', '#888'], 'line-width' => 1.5]"
        :hover-paint="['line-width' => 3, 'line-opacity' => 1]"
    >
        <x-slot:tooltip><strong>{city}</strong> by {mode}</x-slot:tooltip>
    </x-map-arc>
</x-map>

Every key besides from/to becomes a feature property, usable in paint expressions and {placeholders} (values are HTML-escaped).

Slots: tooltip (follows the cursor) and popup (on click). Events: map:arc-hovered and map:arc-clicked with id, arc (your original datum, null on leave), lat, lng.

GeoJSON (<x-map-geojson>)

Render any GeoJSON: polygons get a fill and an outline, lines a line, and points a circle. Great for service areas, delivery zones, choropleths and boundaries.

<x-map :center="[-122.41, 37.77]" :zoom="12">
    <x-map-geojson
        id="area"
        :data="$area"
        interactive
        :fill-paint="['fill-color' => '#3b82f6', 'fill-opacity' => 0.25]"
        :fill-hover-paint="['fill-opacity' => 0.45]"
        :line-paint="['line-color' => '#2563eb', 'line-width' => 2]"
    >
        <x-slot:tooltip>{name}</x-slot:tooltip>
        <x-slot:popup><strong>{name}</strong><br>Population: {population}</x-slot:popup>
    </x-map-geojson>
</x-map>

For a map with no basemap (e.g. a world choropleth), use <x-map blank> and :line-paint="false".

Slots: tooltip and popup with {property} placeholders. Events: map:geojson-hovered and map:geojson-clicked with id, feature (id, properties, geometry; null on leave), lat, lng.

Advanced Usage

Livewire Interactivity

The package dispatches events to Livewire and listens for specific commands.

Events Dispatched (Outbound)

Map Events

Every event detail also includes mapId, so a component can tell maps apart.

Locate Events

Marker Events

Popup Events

Route Events

Route Group Events

Cluster Events

Arc & GeoJSON Events

Route List Events

Custom Events

You can forward any MapLibre event by adding event names to the :events prop or the custom_events config array. They are dispatched as map:{event-name}.

<x-map :events="['movestart', 'idle']">
    <!-- Dispatches map:movestart and map:idle -->
</x-map>

Commands Listened (Inbound)

You can trigger these from your Livewire component using $this->dispatch(). Add a mapId (the map's id attribute) to target one map; without it, every map on the page reacts.

Dynamic Data Commands

Most of the time you don't need these: components inside <x-map> already update when your Livewire properties change. Use the commands for high-frequency updates (live tracking, sliders) to skip the re-render.

Example: Fly To Location

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

Example: Call MapLibre Method Directly

// In Livewire Component
public function setMaxZoom()
{
    $this->dispatch('map:call', [
        'method' => 'setMaxZoom',
        'args' => [18],
    ]);
}

Theme Awareness

By default (theme="auto"), the map follows a dark/light class or a data-theme attribute on your html element, and swaps styles when it changes. Your markers, routes, arcs and layers are re-added automatically after the swap. Set follow_system_theme to also follow the OS preference. You can also force a specific theme using theme="light" or theme="dark".

You can provide separate style URLs for light and dark modes:

<x-map
    light-style="https://example.com/light-style.json"
    dark-style="https://example.com/dark-style.json"
    theme="auto"
/>

Controlled Viewport

You can track and control the map viewport (center, zoom, bearing, pitch) by listening to events and using Alpine.js for real-time reactivity, similar to React's onViewportChange.

Example: Reactive Viewport Dashboard

<div x-data="{
    viewport: {
        lat: 40.7128,
        lng: -74.006,
        zoom: 8,
        bearing: 0,
        pitch: 0
    }
}" class="relative w-full h-[400px]">

    <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"
    />

    <div class="absolute top-2 left-2 z-10 flex gap-3 text-xs font-mono bg-white/90 backdrop-blur p-2 rounded border shadow-sm">
        <span><b class="text-gray-500">lng:</b> <span x-text="viewport.lng.toFixed(3)"></span></span>
        <span><b class="text-gray-500">lat:</b> <span x-text="viewport.lat.toFixed(3)"></span></span>
        <span><b class="text-gray-500">zoom:</b> <span x-text="viewport.zoom.toFixed(1)"></span></span>
        <span><b class="text-gray-500">bearing:</b> <span x-text="viewport.bearing.toFixed(1)"></span>°</span>
        <span><b class="text-gray-500">pitch:</b> <span x-text="viewport.pitch.toFixed(1)"></span>°</span>
    </div>
</div>

Event Reference for Viewport

Alpine.js Directives

The package registers the following Alpine.js directives:

The $map magic returns the MapLibre instance of the enclosing map, e.g. x-on:click="$map.zoomIn()".

From plain JavaScript use window.LivewireMap:

LivewireMap.getMap('main');               // MapLibre Map
LivewireMap.waitForMap('main', (map) => {}); // after the style has loaded
LivewireMap.getRoute('delivery').setProgress(0.8, 1000);

| x-map-marker-popup | Sub-directive for marker popup configuration. | | x-map-marker-tooltip | Sub-directive for marker tooltip configuration. |

GeoJSON Helper

The GeoJSON::fromArray() helper converts simple PHP arrays into GeoJSON FeatureCollections:

use Kwasii\LivewireMapcn\Support\GeoJSON;

$geoJson = GeoJSON::fromArray([
    ['lat' => 51.505, 'lng' => -0.09, 'properties' => ['name' => 'Location 1']],
    ['lat' => 51.51,  'lng' => -0.1,  'properties' => ['name' => 'Location 2']],
]);

// Also passes through existing GeoJSON Feature objects:
$geoJson = GeoJSON::fromArray([
    ['type' => 'Feature', 'geometry' => [...], 'properties' => [...]],
]);

Performance Tips

• Use clusters for large datasets: Always use <x-map-cluster-layer> instead of individual <x-map-marker> tags for datasets over ~100 points.
• Tune cluster radius: Larger :cluster-radius values (e.g., 80) produce fewer clusters and faster rendering.
• Lower cluster max zoom: Setting :cluster-max-zoom="12" stops unclustering at lower zoom levels, reducing visible point counts.
• Cluster size stops: Customize :cluster-size-stops to control circle sizes at different point counts.
• Increase tolerance: :tolerance="0.8" simplifies geometries for faster tile generation at the cost of precision.
• Increase buffer: :buffer="512" reduces tile-edge artefacts during fast panning (uses more memory).
• Throttled events: Continuous map events (map:move, map:zoom, map:bearing-changed, map:pitch-changed) are throttled to 100ms to prevent frame drops. Final values are still delivered via moveend/zoomend events.
• Dynamic updates: Use map:update-cluster-data-{id}, map:update-route-data-{id}, and map:update-route-group-{id} Livewire events to update data without re-rendering the entire component.
• Lazy maps: maps are created only when they come within 300px of the viewport, and maps in hidden tabs or modals wait until shown, so pages with many maps don't boot them all at once. Commands like map:fly-to sent to a map that hasn't started are queued. Use :lazy="false" for a map you must reach immediately from JavaScript.
• Early downloads: @livewireMapStyles (in <head>) preloads MapLibre and preconnects to the CDN and tile hosts. Add your own tile/style hosts to the preconnect config.
• Directions: OSRM results are cached for the browser session (reloads and wire:navigate reuse them), requests time out after 10s and fall back to straight lines, and routes on lazy maps only fetch once their map starts. The public router.project-osrm.org demo server is rate-limited and sometimes slow; set osrm_url to your own OSRM instance in production.
• Data transport: cluster, arc, GeoJSON and route-group data ships in a JSON <script> block rather than an HTML attribute. :max-features-to-inline is deprecated and ignored.
• Directions caching: identical OSRM requests are cached in the browser, and stale requests are aborted when waypoints change.
• Assets: the package JS/CSS URLs carry a content hash and are served with long-lived cache headers.

Upgrading from v1

Most apps upgrade without code changes. Check these:

• MapLibre v6 is ESM-only. If you published the config, set cdn_url and cdn_css_url to null (or point cdn_url at a .mjs file). To stay on v5, set cdn_url to a v5 maplibre-gl.js URL.
• Re-publish views if you published them (php artisan vendor:publish --tag=livewire-mapcn-views --force). Old published views still work but miss new features.
• Reactivity. <x-map> now uses wire:ignore.self, so child components update when Livewire re-renders. Remove any wire:ignore you wrapped around maps, and add wire:key to markers rendered in loops.
• Events are delivered once. v1 sent every event twice to Livewire listeners (and .window Alpine listeners). If you worked around duplicates, remove the workaround.
• Defaults that changed: <x-marker-popup> / <x-marker-tooltip> anchor automatically with a 16px offset; :with-stops draws dots at your waypoints only; cluster circles are slightly smaller ([[0, 18], [100, 26], [1000, 34]]); height="full" now renders as 100%.
• Tailwind is optional. Component styling no longer depends on your Tailwind build scanning the package views.