API Reference

Docs / 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.

Components

<x-map>

The base component for any map. Supports providers, themes, and viewport control.

<x-map-controls>

Zoom, compass, geolocation, fullscreen, and scale controls.

<x-map-marker>

Interactive markers with labels, tooltips, popups, and custom content.

<x-map-popup>

Standalone popups anchored to specific coordinates on the map.

<x-map-route>

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

<x-map-cluster-layer>

Efficiently handle thousands of markers with clustering.

Livewire Events

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

Events Dispatched to Livewire

Event	Payload	Description
map:loaded	—	Map style is fully loaded
map:click	lat, lng, detail	User clicked on the map
map:zoom-changed	zoom	Zoom level changed
map:center-changed	lat, lng	Map center changed
map:marker-clicked	id, lat, lng	A marker was clicked
map:marker-drag-end	id, lat, lng	A draggable marker was released

Commands from Livewire

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

Command	Description
map:fly-to	Move the map smoothly to a new location
map:set-zoom	Change zoom level
map:fit-bounds	Fit the map view to specific coordinates
map:resize	Force a map recalculation (useful for show/hide containers)

Example: Fly To

php — Livewire Component

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

Viewport Events

Track and control the map viewport (center, zoom, bearing, pitch) using Alpine.js events:

Event	Detail	Description
map:move	lat, lng	Fired continuously as the map moves
map:center-changed	lat, lng	Fired once movement ends
map:zoom	zoom	Fired continuously during zoom
map:zoom-changed	zoom	Fired once zoom ends
map:bearing-changed	bearing	Fired when the map is rotated
map:pitch-changed	pitch	Fired when the map is tilted

Tile Providers

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

Provider	Description
carto-voyager	Clean, labelled basemap (default)
carto-positron	Light, minimal basemap
carto-dark-matter	Dark basemap for dark mode
osm-raster	OpenStreetMap raster tiles
custom	Use with style prop for custom MapLibre JSON

Previous ← Installation Next Map →