README

A Livewire component for interactive maps with Leaflet.js integration. Core package for the LBCDev Maps Suite.

Features

• 🗺️ Interactive Maps: Full Leaflet.js integration via Alpine.js
• 🎯 Single & Multi Marker: Support for single markers or marker collections
• 🔄 Reactive Updates: Real-time map updates with Livewire
• 📍 Coordinate Validation: Built-in validation for latitude/longitude
• ⚡ Events System: Emit and listen to map events
• 🎨 Customizable: Extensive configuration options
• ✅ Well Tested: 13 comprehensive tests
• 📚 Fully Documented: Complete API documentation

Requirements

• PHP 8.1 or higher
• Laravel 10.x or 11.x
• Livewire 3.x
• lbcdev/map-geometries

Installation

composer require lbcdev/livewire-maps-core

Publish the configuration file:

php artisan vendor:publish --tag="livewire-maps-config"

Quick Start

Basic Usage

@livewire('livewire-map', [
    'center' => ['lat' => 40.7128, 'lng' => -74.0060],
    'zoom' => 13
])

With Single Marker

use LBCDev\MapGeometries\Marker;

$marker = Marker::make(40.7128, -74.0060, 'New York City')
    ->tooltip('The Big Apple')
    ->iconColor('blue');

@livewire('livewire-map', [
    'marker' => $marker,
    'center' => ['lat' => 40.7128, 'lng' => -74.0060],
    'zoom' => 13
])

With Multiple Markers

use LBCDev\MapGeometries\Marker;
use LBCDev\MapGeometries\MarkerCollection;

$markers = new MarkerCollection();

$markers->add(
    Marker::make(40.7128, -74.0060, 'New York')
        ->iconColor('blue')
);

$markers->add(
    Marker::make(51.5074, -0.1278, 'London')
        ->iconColor('red')
);

@livewire('livewire-map', [
    'markers' => $markers,
    'center' => ['lat' => 40.7128, 'lng' => -74.0060],
    'zoom' => 3
])

Configuration

The package comes with sensible defaults, but you can customize everything:

// config/livewire-maps.php

return [
    'default_center' => [
        'lat' => env('LIVEWIRE_MAPS_DEFAULT_LAT', 0),
        'lng' => env('LIVEWIRE_MAPS_DEFAULT_LNG', 0),
    ],
    
    'default_zoom' => env('LIVEWIRE_MAPS_DEFAULT_ZOOM', 10),
    
    'tile_layer' => [
        'url' => 'https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png',
        'attribution' => '© OpenStreetMap contributors',
    ],
    
    'default_options' => [
        'scrollWheelZoom' => true,
        'dragging' => true,
        'zoomControl' => true,
    ],
];

Component API

Properties

Methods

Computed Properties

Events

Emitted Events

// Coordinates updated
$this->dispatch('map-coordinates-updated', [
    'lat' => 40.7128,
    'lng' => -74.0060
]);

Listening to Events

protected $listeners = [
    'fly-to-coordinates' => 'flyTo',
];

public function flyTo(array $data)
{
    // $data = ['lat' => X, 'lng' => Y, 'zoom' => Z]
}

Advanced Usage

Custom Map Options

@livewire('livewire-map', [
    'center' => ['lat' => 40.7128, 'lng' => -74.0060],
    'zoom' => 13,
    'options' => [
        'scrollWheelZoom' => false,
        'minZoom' => 10,
        'maxZoom' => 18,
        'maxBounds' => [
            [40.5, -74.5],
            [40.9, -73.5]
        ],
    ]
])

Read-Only Mode

@livewire('livewire-map', [
    'marker' => $marker,
    'interactive' => false
])

Custom Height

@livewire('livewire-map', [
    'center' => ['lat' => 40.7128, 'lng' => -74.0060],
    'height' => '700px'
])

Legacy Mode (Separate lat/lng)

For backward compatibility:

@livewire('livewire-map', [
    'latitude' => 40.7128,
    'longitude' => -74.0060
])

Using in Livewire Components

use Livewire\Component;
use LBCDev\MapGeometries\Marker;
use LBCDev\MapGeometries\MarkerCollection;

class LocationPicker extends Component
{
    public ?Marker $selectedLocation = null;
    public MarkerCollection $locations;
    
    protected $listeners = [
        'map-coordinates-updated' => 'handleLocationSelected'
    ];
    
    public function mount()
    {
        $this->locations = new MarkerCollection();
        
        // Add some locations
        $this->locations->add(
            Marker::make(40.7128, -74.0060, 'New York')
        );
    }
    
    public function handleLocationSelected($data)
    {
        $this->selectedLocation = Marker::make(
            $data['lat'],
            $data['lng'],
            'Selected Location'
        );
    }
    
    public function render()
    {
        return view('livewire.location-picker');
    }
}

Testing

composer test

With coverage:

composer test-coverage

Changelog

Please see CHANGELOG for more information on what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email luinux81@gmail.com instead of using the issue tracker.

Credits

• Luinux81
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Related Packages

This package is part of the LBCDev Maps Suite:

• map-geometries - Map geometry classes (Marker, Polyline, etc.)
• filament-maps-fields - Map form fields for Filament
• filament-maps-widgets - Map widgets for Filament panels
• lbcdev-filament-maps-suite - Meta-package for all components