Getting Started
Introduction
livewire-mapcn is a Laravel Livewire package that allows you to easily integrate beautiful, interactive maps into your Laravel applications. Built on top of MapLibre GL JS, it provides a set of expressive Blade components that make mapping effortless.
Prerequisites
Before installing livewire-mapcn, ensure your environment meets the following requirements:
- PHP: 8.3 or higher
- Laravel: 11, 12 or 13
- Livewire: 3 or 4
- Alpine.js: Included automatically with Livewire 3 & 4
Tailwind CSS is not required: the package stylesheet styles every component. MapLibre GL JS (v6 by default) is loaded from a CDN by @livewireMapScripts.
Core Concepts
Declarative Maps
Define your map and its features using expressive Blade tags.
Livewire Integration
Markers, routes and layers update reactively from your component state, and map events reach your PHP component.
Theme Support
Light, dark and auto themes. Auto follows a dark/light class or data-theme on <html>, and optionally the OS preference.
Extensibility
Custom providers, MapLibre style JSON, custom controls with $map, and custom event forwarding.
Features
- Markers with custom HTML content, labels, tooltips and popups (Markers)
- Popups anchored to coordinates (Popups)
- Routes: polylines, real driving/walking/cycling directions via OSRM, route groups and lists, route progress and route markers (<x-map-route-marker>) that ride along a route (Routes)
- Arcs: curved lines connecting pairs of points with <x-map-arc> (Arcs)
- GeoJSON overlays: fills, lines and circles from any GeoJSON with <x-map-geojson> (GeoJSON)
- Clusters for thousands of points, with stepped cluster colors (Clusters)
- Controls: zoom, compass, locate, fullscreen, scale, a 3D view toggle, and custom controls with <x-map-control> that drive the map through the $map Alpine magic (Controls)
- Globe projection, pitch, bearing, bounds and theming on <x-map> (Map)
- Reactive Livewire state: children of <x-map> re-render with your component, no wire:ignore needed (use wire:key in loops)
Quick Preview
Here's a simple map rendered with just a single line of Blade code:
Available Components
The package provides several Blade components, all nested inside the root <x-map> component:
| Component | Description |
|---|---|
| <x-map> | Base map component — required wrapper for all others |
| <x-map-controls> | Zoom, compass, geolocation, fullscreen, scale and 3D view controls |
| <x-map-control> | Custom control buttons that use the $map Alpine magic to reach the MapLibre map |
| <x-map-marker> | Interactive markers with labels, tooltips, and popups |
| <x-map-popup> | Standalone popups anchored to coordinates |
| <x-map-route> | Draw polylines or fetch real driving/walking/cycling directions |
| <x-map-route-group> | Render multiple selectable routes on the same map |
| <x-map-route-list> | Overlay UI panel for displaying route alternatives |
| <x-map-route-marker> | Marker placed along a route, e.g. at its progress point |
| <x-map-arc> | Curved arcs connecting pairs of points |
| <x-map-geojson> | GeoJSON overlays rendered as fills, lines and circles |
| <x-map-cluster-layer> | Efficient clustering for thousands of markers |