Search by

eduardoribeirodev / filament-leaflet

eduardoribeirodev

Um widget de mapa para FilamentPHP.

Package info

github.com/eduardoribeirodev/filament-leaflet

pkg:composer/eduardoribeirodev/filament-leaflet

Statistics

Installs: 59 916

Dependents: 0

Suggesters: 0

Stars: 30

Open Issues: 2

v6.2.0 2026-11-16 17:03 UTC

README

Latest Version on Packagist License Downloads

A powerful and elegant Leaflet integration for Filament PHP that makes creating interactive maps a breeze. Build beautiful, feature-rich maps with markers, clusters, shapes, and more using a fluent, expressive API.

Features

  • Filament Integration - Ready-to-use components including MapPicker (Forms), MapColumn (Tables), and MapEntry (Infolists) for seamless coordinate picking, JSON storage, and visualization.
  • Advanced Map Controls & Layers - Full Leaflet integration for interactive or static (read-only) maps. Control dragging, zooming, and auto-centering. Includes built-in support for OSM, Satellite, Mapbox, and custom tile layers.
  • Smart Markers & Clusters - Intelligent clustering with popup/tooltip support, dynamic sizing, and native Filament Heroicons integration (automatic SVG rendering).
  • Shapes & Drawing - Draw, edit, and manage circles, polygons, polylines, and rectangles directly on the map. Group elements with Layer Groups and automatic coverage area calculation.
  • Eloquent & Data Binding - Easily map models to markers/shapes (via fromRecord()). Features single-column JSON coordinate storage and a dedicated Coordinate DTO.
  • Interactive CRUD & Events - Catch click events on maps, markers, and shapes. Perform built-in view, create, edit, and delete actions directly from the map UI.
  • GeoJSON Support - Load boundaries from URLs, Laravel storage, or inline GeoJSON and build choropleth maps with custom color scales.
  • GeoSearch & Geocoding - Built-in search input supporting Nominatim, Google Maps, Mapbox, and Bing Maps, returning highly detailed Address Value Objects.
  • Robust Architecture - Highly customizable interface built on a solid BaseLayer structure with full Livewire compatibility.

Installation

composer require eduardoribeirodev/filament-leaflet

Publish the assets:

php artisan filament:assets

This publishes the Leaflet CSS and JavaScript. To use the bundled administrative boundaries, also publish the GeoJSON files.

Configuration

You can configure default values for the package in config/filament-leaflet.php:

return [
    'columns' => [ // Default column names for model binding (can be overridden in fromRecord() methods)
        'latitude' => 'lat',
        'longitude' => 'lng',
        'coords' => 'location',
        'radius' => 'radius',
        'title' => 'title',
        'description' => 'description',
        'bounds' => 'bounds',
        'points' => 'points',
    ],
    'sync_record_attributes' => true, // Auto-sync changes back to models
    'default_map_center' => [-14.235, -51.9253], // Default map center
];

Publish the configuration file:

php artisan vendor:publish --tag=filament-leaflet-config

For Mapbox tile layers, configure your access token in your environment or in config/services.php:

MAPBOX_ACCESS_TOKEN=your_mapbox_access_token_here
MAPBOX_TILE_SIZE=512
// config/services.php
'mapbox' => [
    'token' => env('MAPBOX_ACCESS_TOKEN'),
    'tile_size' => env('MAPBOX_TILE_SIZE', 512),
],

Core Components

Map Widget

Create your first interactive map widget:

namespace App\Filament\Widgets;

use EduardoRibeiroDev\FilamentLeaflet\Widgets\MapWidget;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Marker;

class MyMapWidget extends MapWidget
{
    protected ?string $heading = 'My Locations';
    protected array $mapCenter = [-23.5505, -46.6333];
    protected int $defaultZoom = 12;
    protected int $mapHeight = 600;
    
    protected function getMarkers(): array
    {
        return [
            Marker::make(-23.5505, -46.6333)
                ->title('São Paulo')
                ->popupContent('The largest city in Brazil'),
        ];
    }
}

Widget Example

Basic Configuration

class MyMapWidget extends MapWidget
{
    // Display
    protected ?string $heading = 'Store Locations';
    protected int $mapHeight = 600;
    
    // Map center and zoom
    protected array $mapCenter = [-14.235, -51.9253];
    protected int $defaultZoom = 4;
    protected int $maxZoom = 18;
    protected int $minZoom = 2;
}

Map Interaction Control

Control how users interact with your map:

class MyMapWidget extends MapWidget
{
    // Allow/prevent dragging
    protected bool $mapDraggable = true;
    
    // Allow/prevent zooming (scroll wheel, pinch)
    protected bool $mapZoomable = true;
    
    // Auto-recenter after user pans (in milliseconds)
    // Set to null to disable
    protected ?int $recenterMapTimeout = 5000;  // Recenter after 5 seconds
    
    // Auto-center to user's current location
    protected bool $autoCenter = false;
}

Static Maps - Disable all interactions:

MapPicker::make('location')
    ->static()  // Equivalent to ->mapDraggable(false)->mapZoomable(false)

Controls

Enable/disable map controls:

class MyMapWidget extends MapWidget
{
    protected bool $hasAttributionControl = true;
    protected bool $hasScaleControl = true;
    protected bool $hasZoomControl = true;
    protected bool $hasFullscreenControl = true;
    protected bool $hasSearchControl = true;

    protected bool $hasDrawMarkerControl = true;
    protected bool $hasDrawCircleMarkerControl = true;
    protected bool $hasDrawCircleControl = true;
    protected bool $hasDrawPolylineControl = true;
    protected bool $hasDrawRectangleControl = true;
    protected bool $hasDrawPolygonControl = true;
    protected bool $hasDrawTextControl = true;
    protected bool $hasEditLayersControl = true;
    protected bool $hasDragLayersControl = true;
    protected bool $hasRemoveLayersControl = true;
    protected bool $hasRotateLayersControl = true;
    protected bool $hasCutPolygonControl = true;
}

Map Controls Example

Conditionally show controls at runtime:

protected function hasDrawCircleControl(): bool
{
    return auth()?->user()?->is_admin;
}

Tile Layers

Choose from multiple providers or add custom layers:

use EduardoRibeiroDev\FilamentLeaflet\Enums\TileLayer;

class MyMapWidget extends MapWidget
{
    // Single layer
    protected TileLayer|string|array $tileLayersUrl = TileLayer::OpenStreetMap;
    
    // Multiple layers
    protected TileLayer|string|array $tileLayersUrl = [
        'Street Map' => TileLayer::OpenStreetMap,
        'Satellite' => TileLayer::GoogleSatellite,
        'Custom' => 'https://{s}.tile.custom.com/{z}/{x}/{y}.png',
    ];
}

Widget With Custom Tile Layers Example

Available providers: OpenStreetMap, GoogleStreets, GoogleSatellite, GoogleHybrid, GoogleTerrain, EsriWorldImagery, EsriWorldStreetMap, EsriNatGeo, CartoPositron, CartoDarkMatter, MapboxStreets, MapboxOutdoors, MapboxLight, MapboxDark, MapboxSatellite, MapboxSatelliteStreets, MapboxNavigationDay, MapboxNavigationNight

Mapbox Tile Layer:

To use Mapbox tiles, configure your access token in .env or config/services.php. Then use the Mapbox tile layer in your widget:

use EduardoRibeiroDev\FilamentLeaflet\Enums\TileLayer;

class MyMapWidget extends MapWidget
{
    protected TileLayer|string|array $tileLayersUrl = TileLayer::MapboxStreets;
}

MapPicker (Form Field)

Add an interactive map inside Filament forms. It syncs map clicks to form fields and supports all MapWidget configuration methods.

use EduardoRibeiroDev\FilamentLeaflet\Fields\MapPicker;
use EduardoRibeiroDev\FilamentLeaflet\Enums\TileLayer;

MapPicker::make('location')
    ->height(300)
    ->center(-23.5505, -46.6333)
    ->zoom(11)
    ->autoCenter()  // Auto-center to user's location
    ->tileLayersUrl(TileLayer::OpenStreetMap)
    ->columnSpanFull()

Form Field Example

Load GeoJSON: Store the file reference with the GeoJson cast and create a Boundary from the record:

use EduardoRibeiroDev\FilamentLeaflet\Layers\Boundaries\Boundary;
use EduardoRibeiroDev\FilamentLeaflet\ValueObjects\GeoJson;

class DeliveryZone extends Model
{
    protected function casts(): array
    {
        return ['geojson_file' => GeoJson::class . ':s3'];
    }
}

$boundary = Boundary::fromRecord($deliveryZone, geoJsonColumn: 'geojson_file');

Customize pick marker: Visual feedback when clicking the map:

MapPicker::make('location')
    ->pickMarker(fn(Marker $marker) => $marker->blue()->title('Selected'))

Dynamic configuration: Most methods accept closures:

MapPicker::make('location')
    ->center(fn() => [$lat, $lng])
    ->height(fn($record) => 300)
    ->zoom(fn($record) => $record->zoom_level)
    ->mapDraggable(fn($record) => $record->is_editable)
    ->recenterTimeout(fn($record) => $record->is_read_only ? 3000 : null)

Use a self-hosted Nominatim instance for map search:

use EduardoRibeiroDev\FilamentLeaflet\Enums\GeoSearchProvider;
use EduardoRibeiroDev\FilamentLeaflet\Fields\MapPicker;

MapPicker::make('location')
    ->geoSearchControl()
    ->geoSearchProvider(GeoSearchProvider::Nominatim)
    ->geoSearchEndpoint('https://nominatim.internal.example/search');

You can also pass the URL as the endpoint: argument to geoSearchProvider(). The map uses the public Nominatim search URL by default. The custom URL must be reachable from the browser and allow CORS requests from your app if it is on a different origin.

GeoSearchInput (Form Field)

Search and select locations using multiple geocoding providers:

use EduardoRibeiroDev\FilamentLeaflet\Fields\GeoSearchInput;
use EduardoRibeiroDev\FilamentLeaflet\Enums\GeoSearchProvider;

GeoSearchInput::make('location')
    ->provider(GeoSearchProvider::Nominatim)  // Uses OpenStreetMap
    ->limit(10)                               // Max 10 results
    ->withAddressDetails()                    // Include structured address data
    ->language('ru')                          // Preferred language
    ->countryCodes('ru')                      // Restrict to Russia
    ->cacheResults(3600)                      // Cache for 1 hour
    ->textMode(false)                         // Stores full address instead of  coordinates
    ->columnSpanFull()

GeoSearch Input Example

Advanced Configuration:

// Restrict results to a geographic bounding box
GeoSearchInput::make('location')
    ->provider(GeoSearchProvider::Nominatim)
    ->viewbox(
        minLon: 19.0,   // West
        minLat: 41.0,   // South
        maxLon: 190.0,  // East
        maxLat: 82.0    // North
    )
    ->bounded(true)  // Strictly restrict to viewbox
    ->minSearchLength(3)  // Don't search until user types 3+ chars
    ->useShortLabels(true)  // "Moscow Kremlin" instead of full address

Short Labels GeoSearch Input Example

Form Model Integration:

New selections return a GeoSearchResult (or the selected label when textMode(true) is enabled). If your model uses the Coordinate cast, only latitude and longitude are stored. When editing that record, the field returns the saved Coordinate until another search result is selected, and displays latitude, longitude by default.

To display an address you have stored separately, configure a coordinate label resolver:

GeoSearchInput::make('location')
    ->coordinateLabelUsing(fn ($record): ?string => $record?->full_address)

The callback can also receive Coordinate $coordinate through a parameter named $coordinate and call your application's reverse-geocoding service. Return a string label, or null to use the coordinate fallback. Reverse geocoding is opt-in: this package makes no automatic lookup when loading saved coordinates. Cache lookups in your callback, since label resolution may run more than once; handle provider failures by returning null. A reverse lookup may return a different label from the original search result.

The field returns a GeoSearchResult object containing:

  • coordinate - The selected location's latitude/longitude
  • name - Short place name
  • displayName - Full address
  • address - Structured address with country, city, postcode, etc.
  • type - Location type (building, street, city, etc.)
  • addresstype - More specific type (e.g. "tourism", "shop", "amenity")
  • boundingbox - Geographic bounds of the location
use EduardoRibeiroDev\FilamentLeaflet\Fields\GeoSearchInput;
use EduardoRibeiroDev\FilamentLeaflet\ValueObjects\GeoSearchResult;

GeoSearchInput::make('location')->afterStateUpdated(function (callable $set, GeoSearchResult $state) {
    // Access the selected location's data
    $coordinate = $result->coordinate;  // Coordinate object with lat/lng
    $name = $result->name;              // Short name (e.g. "Eiffel Tower")
    $displayName = $result->displayName; // Full address
    $address = $result->address;        // Structured address data
    $type = $result->type;              // Location type (e.g. "tourism")
    $addresstype = $result->addresstype; // More specific type (e.g. "tourism", "shop", "amenity")

    // Example: Set a separate fields
    $set('full_address', $displayName);
    $set('city', $address->city);
    $set('country', $address->country);
    $set('type', $type);
    $set('addresstype', $addresstype);
})

Address Components:

The Address object provides structured address data:

$address = $result->address;

$address->country;       // "Brazil"
$address->countryCode;   // "BR"
$address->state;         // "São Paulo"
$address->city;          // "São Paulo"
$address->county;        // County name
$address->postcode;      // Postal code
$address->suburb;        // Suburb/neighborhood

MapColumn (Table Column)

Display maps directly in Filament table columns:

use EduardoRibeiroDev\FilamentLeaflet\Tables\MapColumn;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Marker;

MapColumn::make('location')
    ->height(100)
    ->zoom(8)
    ->pickMarker(fn(Marker $marker) => $marker->black())
    ->static()    // Disable interactions in table preview

Table Column Example

Display circular maps for a unique visual style:

MapColumn::make('location')
    ->height(72)
    ->zoom(5)
    ->pickMarker(fn(Marker $marker) => $marker->iconSize([14, 25]))
    ->circular()  // Optional: circular display

Table Column Example

MapEntry (Infolist)

Display read-only maps in Filament infolists:

use EduardoRibeiroDev\FilamentLeaflet\Infolists\MapEntry;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Marker;

MapEntry::make('location')
    ->height(284)
    ->zoom(10)
    ->pickMarker(fn(Marker $marker) => $marker->red())
    ->static()    // Disable interactions (enabled by default)
    ->columnSpanFull()

Auto-recenter: Maps automatically recenter after 3 seconds when users pan around. This provides a guided viewing experience while allowing temporary exploration:

    ->recenterTimeout(5000)  // Recenter after 5 seconds (null to disable)

Infolist Entry Example

Map Elements

Markers

Creating Markers

use EduardoRibeiroDev\FilamentLeaflet\Layers\Marker;
use Filament\Support\Colors\Color;

protected function getMarkers(): array
{
    return [
        Marker::make(-23.5505, -46.6333)->title('Simple marker'),
        Marker::make(-23.5212, -46.4243)->green()->title('Colored marker'),
        Marker::make(-23.5266, -46.5412)->icon('https://leafletjs.com/examples/custom-icons/leaf-red.png', [32, 72]),
        Marker::make(-23.5300, -46.6400)->violet()->icon('heroicon-user-circle')->title('Heroicon marker'),
    ];
}

Markers Example

Marker Icons

Markers support multiple icon types with different visual behaviors:

Custom Icon URL (replaces the entire marker):

Marker::make(-23.5505, -46.6333)
    ->icon('https://example.com/icon.png', [54, 54])
    ->title('Custom Icon Marker')

Custom Icon Marker Example

When using a custom icon URL, the entire marker is replaced with your custom image - the marker's color is ignored.

Heroicons (Filament Icons) (icon in center):

use Filament\Support\Icons\Heroicon;

Marker::make(-23.5505, -46.6333)
    ->icon(Heroicon::BuildingLibrary)        // Using Heroicon enum
    ->icon('heroicon-building-library')      // Using string
    ->heroicon('building-library')           // Using explicit heroicon() method
    ->iconSize([36, 54])
    ->title('Heroicon Marker')
    ->color(Color::Indigo);

Heroicon Marker Example

When using Heroicons, the marker keeps its default styled appearance with the color gradient, and the Heroicon is automatically rendered in the center in white. The marker's color settings (.blue(), .red(), etc.) are fully respected.

Icon Appearance:

  • Icon URL: Fully replaces marker appearance (color is ignored)
  • Heroicon: Keeps marker style (with color gradient) with the icon rendered in the center

Marker Colors

Markers accept colors in multiple formats:

Using Color Class:

Marker::make(-23.5505, -46.6333)
    ->color(Color::Blue)  // Color class constant
    ->blue()              // Convenience method

Using string formats:

Marker::make(-23.5505, -46.6333)
    ->color('#3388ff')           // Hex color
    ->color('rgb(51, 136, 255)') // RGB color
    ->color('oklch(59% 0.15 262)')  // OKLCH color

Available convenience methods: blue(), red(), green(), orange(), yellow(), violet(), gray(), black(), gold(), randomColor()

From Eloquent Models

// Basic usage
Marker::fromRecord(
    record: $store,
    coordsColumn: 'coordinates',  // Column/attribute with Coordinate value object
    titleColumn: 'name',
    descriptionColumn: 'description',
    popupFieldsColumns: ['address', 'phone'],
    color: Color::Blue,
);

// With custom callback
Marker::fromRecord(
    record: $store,
    coordsColumn: 'coordinates',
    mapRecordCallback: function (Marker $marker, Model $record) {
        $marker->gold()->popupFields(['hours' => $record->hours]);
    }
);

Note: The coordsColumn parameter expects a Coordinate value object. Configure your model like this:

use EduardoRibeiroDev\FilamentLeaflet\ValueObjects\Coordinate;

class Store extends Model
{
    protected $casts = [
        'coordinates' => Coordinate::class,
    ];
}

Layer Groups

Layer groups are a powerful way to organize and manage multiple layers on your map. They allow you to:

  • Toggle visibility - Show/hide entire groups of layers at once
  • Organize layers - Group related markers and shapes together
  • Improve performance - Manage large datasets efficiently
  • Control layer management - Add/remove layers from groups dynamically

Layer Group

A simple container for organizing related layers. Perfect for grouping logically related markers and shapes without any automatic behavior:

use EduardoRibeiroDev\FilamentLeaflet\LayerGroups\LayerGroup;

protected function getMarkers(): array
{
    return [
        LayerGroup::make([
            Marker::make(-23.5505, -46.6333)->title('Store 1'),
            Marker::make(-23.5515, -46.6343)->title('Store 2'),
            Marker::make(-23.5525, -46.6353)->title('Store 3'),
        ])
        ->name('Active Stores')
        ->id('active-stores'),
    ];
}

Using the group() helper method (shorthand):

Instead of wrapping layers in LayerGroup::make(), you can use the group() method on any layer to automatically group multiple layers:

protected function getMarkers(): array
{
    return [
        Marker::make(-23.5505, -46.6333)
            ->title('Store 1')
            ->group('Active Stores'),
        
        Marker::make(-23.5515, -46.6343)
            ->title('Store 2')
            ->group('Active Stores'),
        
        Marker::make(-23.5525, -46.6353)
            ->title('Store 3')
            ->group('Active Stores'),
    ];
}

Layer Group Example

Feature Group

Creates a polygon envelope around all layers in the group. This is useful for visualizing the coverage area or boundary of a set of points:

use EduardoRibeiroDev\FilamentLeaflet\LayerGroups\FeatureGroup;

protected function getMarkers(): array
{
    return [
        FeatureGroup::make([
            Marker::make(-23.5505, -46.6333)->title('Point 1'),
            Marker::make(-23.5515, -46.6343)->title('Point 2'),
            Marker::make(-23.5525, -46.6323)->title('Point 3'),
        ])
            ->name('Delivery Zone')
            ->blue()
            ->fillBlue()
            ->fillOpacity(0.3)
            ->weight(3)
            ->dashArray(5, 10),
    ];
}

Feature Group Example

Marker Cluster

Groups nearby markers into clusters for better performance and visual clarity, especially with large datasets. Clusters automatically expand when zooming in:

use EduardoRibeiroDev\FilamentLeaflet\LayerGroups\MarkerCluster;

protected function getMarkers(): array
{
    return [
        MarkerCluster::make([
            Marker::make(-23.5505, -46.6333)->title('Location 1'),
            Marker::make(-23.5515, -46.6343)->title('Location 2'),
            Marker::make(-23.5525, -46.6353)->title('Location 3'),
        ])
        ->maxClusterRadius(80)
        ->showCoverageOnHover()
        ->name('Locations')
        ->spiderfyOnMaxZoom(),
    ];
}

Marker Cluster Example

Cluster from Model:

Create clusters directly from Eloquent models with powerful customization:

use App\Models\Store;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Marker;
use Filament\Support\Colors\Color;

protected function getMarkers(): array
{
    return [
        MarkerCluster::fromModel(
            model: Store::class,
            coordsColumn: 'coordinates',  // Column/attribute with Coordinate value object
            titleColumn: 'name',
            descriptionColumn: 'description',
            popupFieldsColumns: ['address', 'phone'],
            color: Color::Green,
        )
        ->maxClusterRadius(60)
        ->disableClusteringAtZoom(15),
    ];
}

Cluster with Query Modification:

Filter and customize the query used to load markers:

MarkerCluster::fromModel(
    model: Store::class,
    coordsColumn: 'coordinates',
    modifyQueryCallback: function ($query) {
        return $query
            ->where('status', 'active')
            ->where('city', 'São Paulo')
            ->orderBy('name');
    },
    mapRecordCallback: function (Marker $marker, Model $record) {
        // Customize each marker based on record properties
        if ($record->isPremium()) {
            $marker->gold()->icon('/images/premium-icon.png');
        }
        
        // Add status-based styling
        match($record->status) {
            'open' => $marker->green(),
            'busy' => $marker->orange(),
            'closed' => $marker->red(),
            default => $marker->gray(),
        };
        
        // Add popup with custom fields
        $marker->popupFields([
            'manager' => $record->manager_name,
            'staff' => $record->staff_count . ' employees',
            'rating' => $record->rating . ' ⭐',
        ]);
    }
);

Advanced cluster configuration:

MarkerCluster::make($markers)
    ->maxClusterRadius(80)              // Cluster radius in pixels
    ->showCoverageOnHover(true)         // Highlight cluster area on hover
    ->zoomToBoundsOnClick(true)         // Zoom to cluster bounds when clicked
    ->spiderfyOnMaxZoom(true)           // Spread markers at max zoom
    ->removeOutsideVisibleBounds(true)  // Remove markers outside viewport for performance
    ->disableClusteringAtZoom(15)       // Stop clustering at zoom level 15+
    ->animate(true);                    // Animate cluster changes;

Shapes

Draw various geometric shapes on your map:

Circles

Circles with radius in various units:

use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Circle;

protected function getShapes(): array
{
    return [
        Circle::make(-23.5505, -46.6333)
            ->popupContent('10km radius coverage')
            ->title('Service Area')
            ->blue()
            ->fillBlue()
            ->fillOpacity(0.2)
            ->radius(10000)           // Radius in meters (default)
            ->radiusInKilometers(10)  // Radius in kilometers
            ->radiusInMiles(6.2)      // Radius in miles
            ->radiusInFeet(32808)     // Radius in feet
    ];
}

Circles Example

Circle Markers

Small circles with pixel-based radius (like markers but circular):

use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\CircleMarker;

CircleMarker::make(-23.5505, -46.6333)
    ->radius(45) // Radius in pixels
    ->red()
    ->fillRed()
    ->weight(2)
    ->title('Point of Interest');

Circle Markers Example

Polygons

Draw custom polygons:

use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Polygon;

// Define a polygon area
Polygon::make(
    [-23.5505, -46.6333],
    [-23.5515, -46.6343],
    [-23.5525, -46.6323],
    [-23.5505, -46.6333], // Close the polygon
)
->green()
->fillGreen()
->fillOpacity(0.3)
->title('Delivery Zone')
->popupContent('We deliver to this area');

// Or build point by point
Polygon::make()
    ->addPoint(-23.5505, -46.6333)
    ->addPoint(-23.5515, -46.6343)
    ->addPoint(-23.5525, -46.6323)
    ->addPoint(-23.5505, -46.6333)
    ->blue();

Polygons Example

Polylines

Draw lines connecting multiple points:

use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Polyline;

// Route or path
Polyline::make(
    [-23.5505, -46.6333],
    [-23.5515, -46.6343],
    [-23.5525, -46.6353],
    [-23.5535, -46.6363],
)
->blue()
->weight(4)
->opacity(0.7)
->dashArray('10, 5')      // Dashed line
->smoothFactor(1.5)       // Smooth curves
->title('Delivery Route');

// Or build incrementally
Polyline::make()
    ->addPoint(-23.5505, -46.6333)
    ->addPoint(-23.5515, -46.6343)
    ->addPoint(-23.5525, -46.6353)
    ->red()
    ->weight(3);

Polylines Example

Rectangles

Draw rectangular bounds:

use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Rectangle;

// Using corner coordinates
Rectangle::make(
    [-23.5505, -46.6333],  // Southwest corner
    [-23.5525, -46.6353]   // Northeast corner
)
->orange()
->fillOrange()
->fillOpacity(0.2)
->title('Restricted Area');

// Alternative syntax
Rectangle::makeFromCoordinates(
    -23.5505, -46.6333,    // Southwest lat, lng
    -23.5525, -46.6353     // Northeast lat, lng
)
->red();

Rectangles Example

Shapes from Eloquent Models

All shape classes support fromRecord() factory methods for easy creation from database records:

use App\Models\DeliveryZone;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Circle;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Polygon;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Polyline;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\Rectangle;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Shapes\CircleMarker;

protected function getShapes(): array
{
    return DeliveryZone::all()->map(function ($zone) {
        // Circle from record
        return Circle::fromRecord(
            record: $zone,
            coordsColumn: 'center_coordinates',
            radiusColumn: 'coverage_radius_km',
            titleColumn: 'name',
            descriptionColumn: 'description',
            popupFieldsColumns: ['address', 'radius'],
        );
    })->all();
}

Configure Your Model:

use EduardoRibeiroDev\FilamentLeaflet\ValueObjects\Coordinate;

class DeliveryZone extends Model
{
    protected $casts = [
        'center_coordinates' => Coordinate::class,
    ];
}

Each shape type supports the fromRecord() method with common parameters:

  • record: The Eloquent model instance
  • coordsColumn: Column name for center coordinates (for Circle, CircleMarker) - expects a Coordinate value object
  • radiusColumn: Column name for radius (for Circle, CircleMarker)
  • pointsColumn: Column name for points array (for Polygon, Polyline)
  • boundsColumn: Column name for bounds array (for Rectangle)
  • titleColumn: Column name for the shape title
  • descriptionColumn: Column name for the popup content
  • popupFieldsColumns: Array of column names to include in popup
  • color: Default color for the shape
  • syncRecord: Whether to sync changes back to the record when edited (default: true from config)
  • mapRecordCallback: Closure to customize the shape based on the record
Circle from Record
Circle::fromRecord(
    record: $zone,
    coordsColumn: 'center',
    radiusColumn: 'coverage_radius_km',
    titleColumn: 'zone_name',
    descriptionColumn: 'zone_description',
    mapRecordCallback: fn(Circle $circle, $record) => 
        $circle->radiusInKilometers($record->coverage_radius_km)
);
Polygon from Record
// Assumes database structure: points => [[lat, lng], [lat, lng], ...]
Polygon::fromRecord(
    record: $zone,
    pointsColumn: 'boundary_points',
    titleColumn: 'zone_name',
    popupFieldsColumns: ['area_sqkm', 'population'],
);
Polyline from Record
// Store route as JSON array of [lat, lng] coordinates
Polyline::fromRecord(
    record: $deliveryRoute,
    pointsColumn: 'route_path',
    titleColumn: 'route_name',
    descriptionColumn: 'destination',
    mapRecordCallback: fn(Polyline $line, $record) =>
        $record->is_completed 
            ? $line->green()->weight(2)
            : $line->red()->weight(3)
);
Rectangle from Record
// Assumes database structure: bounds => [[lat1, lng1], [lat2, lng2]]
Rectangle::fromRecord(
    record: $territory,
    boundsColumn: 'service_bounds',
    titleColumn: 'territory_name',
    popupFieldsColumns: ['region', 'sales_person'],
);

Shape Styling

Circle::make(-23.5505, -46.6333)
    ->radius(5000)
    
    // Border styling
    ->color(Color::Blue)        // Border color
    ->weight(3)                 // Border width in pixels
    ->opacity(0.8)              // Border opacity (0-1)
    ->dashArray('5, 10')        // Dashed border pattern
    
    // Fill styling
    ->fillColor(Color::Green)   // Fill color
    ->fillOpacity(0.3)          // Fill opacity (0-1)

Editable Layers

Make markers and shapes editable directly on the map by enabling the draw control:

class MyMapWidget extends MapWidget
{
    protected bool $hasEditLayersControl = true;
    
    protected function getMarkers(): array
    {
        return [
            Marker::make(-23.5505, -46.6333)
                ->title('Editable Marker')
                ->editable(),  // Make this marker editable
            
            Circle::make(-23.5505, -46.6333)
                ->radiusInKilometers(5)
                ->editable(),  // Make this circle editable
        ];
    }
}

You can also make all layers in a group editable:

LayerGroup::make([
    Marker::make(-23.5505, -46.6333)->title('Point 1'),
    Marker::make(-23.5515, -46.6343)->title('Point 2'),
    Marker::make(-23.5525, -46.6353)->title('Point 3'),
])
->name('Editable Points')
->editable(),  // All markers in the group are now editable

User Interactions

Popups and Tooltips

Tooltips (appear on hover)

Marker::make(-23.5505, -46.6333)
    ->tooltip(
        content: 'São Paulo City',
        permanent: false,
        direction: 'top',
        options: ['offset' => [0, -20]]
    );

// Or using individual methods
Marker::make(-23.5505, -46.6333)
    ->tooltipContent('São Paulo')
    ->tooltipPermanent(true)
    ->tooltipDirection('top');

Popups (appear on click)

Marker::make(-23.5505, -46.6333)
    ->popupTitle('Store Location')
    ->popupContent('Visit our main store')
    ->popupFields([
        'address' => '123 Main Street',
        'phone' => '+55 11 1234-5678',
        'email' => 'contact@store.com',
    ])
    ->popupOptions(['maxWidth' => 300]);

// Or use shorthand
Marker::make(-23.5505, -46.6333)
    ->popup(
        content: 'Store description',
        fields: ['address' => '123 Main St', 'phone' => '+55 11 1234-5678'],
        options: ['maxWidth' => 300]
    );

How popup fields work: Keys are automatically converted to title case, underscores replaced with spaces, and translated using Laravel's __() helper. Both keys and values support translation keys.

Combined Usage

Marker::make(-23.5505, -46.6333)
    ->title('Pizza Palace')
    ->popupContent('Best pizza in town')
    ->popupFields([
        'address' => '123 Main St',
        'phone' => '+55 11 1234-5678',
        'rating' => '4.5 ⭐',
    ]);

Click Actions

Marker Click Handler

use Filament\Notifications\Notification;

Marker::make(-23.5505, -46.6333)
    ->title('Interactive Marker')
    ->action(function (Marker $marker) { // Or ->onClick()
        Notification::make()
            ->title('Marker Clicked!')
            ->body('ID: ' . $marker->getId())
            ->send();
    });

Shape Click Handler

Circle::make(-23.5505, -46.6333)
    ->radius(5000)
    ->action(function (Circle $circle) { // Or ->onClick()
        Notification::make()
            ->title('Circle clicked')
            ->send();
    });

From Model Records

protected function getMarkers(): array
{
    return Store::all()->map(function ($store) {
        return Marker::fromRecord($store)->action(function (Marker $marker, Store $record) { // Or ->onClick()
            Notification::make()
                ->title("You clicked: {$record->name}")
                ->body("Address: {$record->address}")
                ->send();
            
            return redirect()->route('stores.show', $record);
        });
    })->all();
}

Map Click Handler

Handle clicks on the map itself:

public function handleMapClick(float $latitude, float $longitude): void
{
    Notification::make()
        ->title('Map clicked')
        ->body("Coordinates: {$latitude}, {$longitude}")
        ->send();
}

Field/Entry/Column Click Handlers

Handle map clicks in form fields, infolists, or table columns:

use EduardoRibeiroDev\FilamentLeaflet\Fields\MapPicker;
use Filament\Notifications\Notification;

MapPicker::make('location')
    ->height(300)
    ->onMapClick(function (float $latitude, float $longitude) {
        Notification::make()
            ->title('Location Selected')
            ->body("Lat: {$latitude}, Lng: {$longitude}")
            ->send();
    });

Handle layer (marker/shape) clicks:

use EduardoRibeiroDev\FilamentLeaflet\Layers\BaseLayer;

MapPicker::make('location')
    ->height(300)
    ->onLayerClick(function (BaseLayer $layer) {
        Notification::make()
            ->title('Layer Clicked')
            ->body("Layer ID: {$layer->getId()} - Type: {$layer->getType()}")
            ->send();
    });

Advanced Features

Model Integration & CRUD Operations

Enable creating markers directly from map clicks:

use App\Models\Location;

class LocationMapWidget extends MapWidget
{
    protected ?string $markerModel = Location::class;
    protected string $coordinatesColumnName = 'coordinates';
    
    protected function getFormComponents(): array
    {
        return [
            TextInput::make('name')->required(),
            ColorPicker::make('color')->rgb(),
            Textarea::make('description')->columnSpanFull(),
        ];
    }
}

When users click the map, a form modal opens to create a new marker. The widget automatically converts latitude/longitude into the configured coordinates column.

Built-in Marker Actions:

Define custom actions to execute when clicking markers with records using the $markerClickAction property:

use App\Models\Store;

class LocationMapWidget extends MapWidget
{
    protected ?string $markerModel = Store::class;
    protected string $coordinatesColumnName = 'coordinates';
    
    // Define the action to execute when a marker is clicked
    protected ?string $markerClickAction = 'view'; // 'view', 'edit', 'delete' or null
    
    protected function getMarkers(): array
    {
        return Store::all()->map(fn($store) => 
            Marker::fromRecord(
                record: $store,
                coordsColumn: 'coordinates',
                titleColumn: 'name',
            )
        )->all();
    }
}

Available marker click actions:

  • 'view' - Display a read-only modal with the marker's record details
  • 'edit' - Open an edit form for the marker's record (default)
  • 'delete' - Prompt to delete the marker's record
  • null - No action

Using a Resource Form:

use App\Filament\Resources\Locations\LocationResource;

class LocationMapWidget extends MapWidget
{
    protected ?string $markerModel = Location::class;
    protected ?string $markerResource = LocationResource::class;
}

Hooks:

protected function afterMarkerCreated(Model $record): void
{
    Notification::make()
        ->title('Location created!')
        ->body("Created: {$record->name}")
        ->success()
        ->send();
}

protected function mutateFormDataBeforeCreate(array $data): array
{
    $data['user_id'] = auth()->id();
    $data['status'] = 'active';
    return parent::mutateFormDataBeforeCreate($data);
}

Keep Maps in Sync with Tables:

use EduardoRibeiroDev\FilamentLeaflet\Concerns\InteractsWithMap;

class ManageLocations extends ManageRecords
{
    use InteractsWithMap;
}

This automatically refreshes the map after create/edit/delete actions.

GeoJSON Boundaries

GeoJSON is represented by a regular map layer. Choose its source explicitly and add it with boundaries():

use EduardoRibeiroDev\FilamentLeaflet\Layers\Boundaries\Boundary;

$map->boundaries([
    Boundary::make()->fromUrl('https://example.com/coverage.geojson'),
]);

Local files and in-memory GeoJSON are supported too:

Boundary::make()->fromStorage('maps/coverage.geojson', disk: 'public');
Boundary::make()->fromGeoJson($featureCollection);

Use feature properties to join external values and create a choropleth:

Boundary::make()
    ->fromUrl('https://example.com/brazil-states.geojson')
    ->features(key: 'shapeISO', label: 'shapeName')
    ->choropleth(
        values: ['BR-SP' => 166.23, 'BR-RJ' => 365.23, 'BR-MG' => 33.41],
        colors: ['#FED976', '#FD8D3C', '#BD0026'],
        missingColor: '#E5E7EB',
    );

When upgrading from the old GeoJSON API, replace geoJsonUrl() or a widget's getGeoJsonUrl() with Boundary::make()->fromUrl($url). Add the layer with boundaries([...]) on a form or infolist component, or return it from getBoundaries() on a widget. Move geoJsonData() and geoJsonColors() into choropleth(), using the feature IDs as keys, and replace geoJsonTooltip() with tooltipContent() on the layer. For models that used HasGeoJsonFile, use fromStorage() for an existing path and disk, or migrate the stored value to the GeoJson cast's file_path and optional disk format before using Boundary::fromRecord().

Use AdministrativeBoundary for built-in administrative layers. Generated country classes in the Countries namespace are static helpers that convert codes and exact catalog names into shapeIDs. They do not inherit layer configuration or create map layers. The package includes Brazil, Germany, Spain, France, Italy, Portugal and the United States.

use EduardoRibeiroDev\FilamentLeaflet\Countries\Brazil;
use EduardoRibeiroDev\FilamentLeaflet\Enums\AdministrativeLevel;
use EduardoRibeiroDev\FilamentLeaflet\Layers\Boundaries\AdministrativeBoundary;

AdministrativeBoundary::make()
    ->restrictTo(Brazil::state('MT'))
    ->values(Brazil::cities('MT', [
        'Cuiabá' => 120,
        'Várzea Grande' => 40,
    ]))
    ->level(AdministrativeLevel::Auto)
    ->colorScale(['#FED976', '#FD8D3C', '#BD0026']);

Singular helpers return a shapeID string. Plural helpers return ordinary shapeID => value arrays:

Brazil::country();                         // Country shapeID
Brazil::state('MT');                       // State shapeID
Brazil::city('MT', 'Cuiabá');               // City shapeID
Brazil::states(['MT' => 20, 'SP' => 50]);   // State IDs mapped to values
Brazil::cities('MT', ['Cuiabá' => 120]);    // City IDs mapped to values

restrictTo() accepts one shapeID, a list of shapeIDs, a closure returning either, or null to clear the limit. values() accepts a map keyed by shapeID, a list of those maps, or a closure. Several countries can share one logical layer and color scale without spreading helper results:

use EduardoRibeiroDev\FilamentLeaflet\Countries\UnitedStates;

AdministrativeBoundary::make()
    ->values([
        Brazil::states(['MT' => 20, 'SP' => 50]),
        UnitedStates::states(['CA' => 80]),
    ])
    ->level(AdministrativeLevel::Auto);

To render countries as independent layers, create separate AdministrativeBoundary instances. Each instance owns its ID, level, colors and other presentation settings:

$map->boundaries([
    AdministrativeBoundary::make()
        ->id('brazil-visits')
        ->restrictTo(Brazil::country())
        ->values($brazilTotalsByShapeId),
    AdministrativeBoundary::make()
        ->id('usa-visits')
        ->restrictTo(UnitedStates::country())
        ->values($usaTotalsByShapeId),
]);

Use the same layer API for a query grouped by persisted municipal IDs:

AdministrativeBoundary::make()
    ->id('visits')
    ->values($totalsByShapeId)
    ->level(AdministrativeLevel::Auto);

state() takes a state code and city() takes an exact catalog name within its state. Unknown codes, unknown names and duplicate city names within one state throw an exception. Every state and city has its own ID even when its source shapeISO is missing or nonstandard. Country classes and their PHPDoc options are generated by npm run build:geojson or npm run build:locations, preserving editor completion for supported codes and names. IDs returned by MunicipalityResolver can be used directly in values() or restrictTo().

All values in a layer must belong to one source level. Finite numeric values are summed for their ancestors. Municipal values can produce state and country totals, and state values can produce country totals. Repeated IDs across value maps add their values. Null values remain missing, and missing regions do not become zero. Use additive metrics such as counts or amounts. Mixed source levels, nonfinite values and overflowing sums throw an exception.

level() controls display independently of the source data. It accepts AdministrativeLevel::Country, State, Municipality or Auto, and also supports a closure returning an enum. Auto is the default and advances only as far as the supplied data. A fixed level more detailed than the values, or coarser than the explicit geographical scope, throws an exception.

An AdministrativeBoundary without restrictTo() infers countries from the supplied IDs and can explore their complete hierarchy up to the source level. Empty helper results are ordinary arrays and carry no country or level information. An empty array uses the explicit scope, or all bundled countries when no scope is selected, and renders ordinary geometry. To keep a filtered dashboard on a specific country and level when no rows match, set both explicitly:

AdministrativeBoundary::make()
    ->restrictTo(Brazil::country())
    ->values(Brazil::states($stateTotals))
    ->level(AdministrativeLevel::State);

To look up a shapeID from a point, use MunicipalityResolver.

use EduardoRibeiroDev\FilamentLeaflet\Support\MunicipalityResolver;
use EduardoRibeiroDev\FilamentLeaflet\ValueObjects\Coordinate;

$resolver = app(MunicipalityResolver::class);
$point = new Coordinate(-15.6014, -56.0979);
$municipality = $resolver->resolve($point);
$state = $resolver->resolve($point, AdministrativeLevel::State);
$country = $resolver->resolve($point, AdministrativeLevel::Country, country: 'BRA');

ADM2 is the default. Each level checks its own polygons, so an ambiguous municipality can still resolve to a state or country. The optional named country argument uses ISO3. The resolver returns null for invalid coordinates, locations outside the bundled coverage and locations matching more than one polygon at the requested level.

Auto uses actual screen coverage and typical municipal size. It shows municipalities only in the focused state, keeping surrounding states at ADM1 and other countries at ADM0. Clicking a state opens its municipalities. Click focus is released when moving away or on the first zoom reduction. The country/state and state/municipality transitions use symmetric entry and exit thresholds. Alaska, Hawaii and the US mainland are evaluated as separate regions. Pending loads use the existing source cache and stale responses cannot replace the geometry for a newer view. Map movement executes no SQL.

Country helpers have no make(), values(), level(), id() or styling methods. Replace direct country layers such as Brazil::states(...)->level(...) with AdministrativeBoundary::make()->values(Brazil::states(...))->level(...). Replace old country-class imports from Layers\Boundaries with Countries. No GeoJSON or JavaScript payload migration is required.

Publish Administrative GeoJSON

Choose which countries to publish:

php artisan filament-leaflet:install-geojson

For each selected country, the command publishes all available levels (ADM0, ADM1 and ADM2) from the bundled files. To publish all seven countries without prompting, run:

php artisan filament-leaflet:install-geojson --all

If you publish only some countries, limit each administrative layer to countries you installed. For example, after publishing Brazil, use AdministrativeBoundary::make()->restrictTo(Brazil::country()). A copy failure makes the command return a nonzero exit code. Rerun it after fixing the reported error.

GeoJSON files are fetched on demand and cached for the life of the map. Switching levels preserves the map's center and zoom, and keeps the previous geometry visible while loading the next one or if loading fails. fitBounds() can frame the initial data; automatic level switches do not reframe the map. The same logical layer and its group, popup, tooltip, and click action are preserved across switches. For Livewire updates, assign an explicit id() when the layer should retain its identity as its configuration changes.

Built-in sources include small bounding boxes generated from the bundled geometry at all administrative levels. Each feature also includes a build-time bbox, so viewport filtering does not traverse its coordinates in the browser. Offscreen countries do not download their country/state files, and at municipal zoom only intersecting state files load. Pans are checked after movement ends (with a short debounce). Within downloaded files, readonly layers draw only features whose bounds intersect the viewport; moving inside the same visible feature set does not rebuild geometry. Returning uses the existing source cache. This uses static GeoJSON requests, with no new Laravel endpoint or database queries on movement. Totals and color scales continue to use all supplied values, so moving the viewport does not change their meaning.

All layers use the same bundled adm0.geojson, adm1.geojson and adm2.geojson files at every zoom, including editable layers. Geometry is simplified at build time with Mapshaper's topology-aware Douglas–Peucker algorithm and a 25-metre distance tolerance. Files belonging to a country are processed together, preserving shared borders, every polygon component and hole, IDs and names. No separate geometry variants are distributed. The coordinate resolver uses these same files, so points close to a border can resolve differently from the unsimplified source. After updating, run the installer again for the countries you use to refresh their files and remove obsolete variants.

npm run build:geojson applies simplification automatically after downloading and splitting source geometry. npm run build:simplify simplifies existing bundled files and regenerates their indexes and country classes. Each file records the method, distance and a geometry checksum; repeating the command skips unchanged simplified geometry to avoid cumulative detail loss. To change the tolerance or combine updated and previously simplified files, rebuild from source with build:geojson. npm run build:locations rebuilds only the catalogs, spatial indexes, bounds metadata and generated country classes from the existing geometry.

During native pan/zoom animations, pending loads may finish into the cache but cannot replace displayed paths. At movement end, the latest viewport and zoom are resolved. A buffered viewport reduces blank edges during animation, and features that remain visible retain their Leaflet path instances, including neighboring states and countries when another region changes level. New geometry is prepared in small batches between animation frames. Readonly Canvas paths are also projected in those batches, remaining invisible and noninteractive until the replacement is ready. Navigation, configuration updates and removal cancel unfinished preparation and discard its staged paths. Style and data changes still update the affected features. A single very large feature remains a synchronous Leaflet operation.

Initial fitBounds() can use those bounding boxes to find offscreen states without downloading all of them. Bounds support wrapped world copies and states crossing the date line. Sources without bounds retain their previous loading behavior, including custom GeoJSON. A shared national ADM2 file still downloads as a whole when any selected state using it becomes visible; its features are filtered locally. Readonly boundaries use a shared Canvas renderer and opt out of Geoman editing initialization. Editable boundaries retain their editing behavior. Choropleth color domains are calculated once for each rendered layer, rather than for every polygon.

Multi-Language Support

The package includes built-in support for: English (en), Portuguese (pt_BR, pt_PT), Spanish (es), French (fr), German (de), Italian (it). Draw control labels, tooltips and messages follow your application's locale.

Administrative region names follow the current Laravel locale automatically. The map receives one regionNames dictionary for that locale, shared by all its layers, and looks up labels by shapeID. The bundled regions.php files cover countries, states and selected ADM2 regions with established translated names. Missing entries use the original GeoJSON shapeName; an unsupported locale also uses the original names. Custom featureLabel() fields keep their configured behavior. Changing the locale and refreshing a Livewire map updates its labels without modifying source geometry, value keys or the names accepted by country helpers.

To customize labels, publish the translations with php artisan vendor:publish --tag=filament-leaflet-translations, then edit lang/vendor/filament-leaflet/{locale}/regions.php. Partial files override only the supplied IDs. For example:

// lang/vendor/filament-leaflet/pt_BR/regions.php
return [
    '88855331B58508533874502' => 'Brasil',
];

Builds validate bundled translation keys against the current geometry index and reject orphan IDs or empty labels. Validation uses the PHP CLI and can also be run with php scripts/validate-region-translations.php. No translated geometry copies or additional HTTP requests are needed.

Best Practices

Performance Optimization

  1. Use Marker Clusters for large datasets:
// Bad: 1000 individual markers
protected function getMarkers(): array
{
    return Store::all()->map(fn($s) => Marker::fromRecord($s))->all();
}

// Good: Clustered markers
protected function getMarkers(): array
{
    return [
        MarkerCluster::fromModel(Store::class)
            ->maxClusterRadius(80)
    ];
}
  1. Limit data with query modifications:
MarkerCluster::fromModel(
    model: Store::class,
    modifyQueryCallback: fn($q) => $q->limit(100)->latest()
)
  1. Use appropriate zoom levels:
protected int $defaultZoom = 12;  // City level
protected int $maxZoom = 18;      // Street level
protected int $minZoom = 3;       // Country level

Debugging

Enable logging for map interactions:

public function handleMapClick(float $latitude, float $longitude): void
{
    logger("Map clicked", compact('latitude', 'longitude'));
}

Configuration Reference

Customization

Custom Styles

Add custom CSS to your map:

public function getCustomStyles(): string
{
    return <<<CSS
        .custom-marker {
            filter: hue-rotate(45deg);
        }
        
        .leaflet-popup-content {
            font-family: 'Inter', sans-serif;
        }
    CSS;
}

Custom Scripts

Execute JavaScript after map initialization:

public function getCustomScripts(): string
{
    return <<<JS
        function customFunction() {
            // Your code
        }
    JS;
}

Method Reference

GeoSearchInput

Method Description
provider($provider) Set geocoding provider (Nominatim, GoogleMaps, Mapbox, BingMaps)
limit($count) Set maximum results (1–50, default 25)
withAddressDetails($enabled) Include structured address in results (default true)
language($code) Set preferred language (e.g., 'pt-BR', 'en')
countryCodes($codes) Restrict results to ISO 3166-1 alpha-2 country codes (e.g., 'br' or ['br', 'ar']). Use language('en') to set the result language.
viewbox($minLon, $minLat, $maxLon, $maxLat) Set bounding box to bias/restrict results
bounded($enabled) Strictly restrict results to viewbox (default false)
cacheResults($ttl) Cache results for given seconds (default 3600)
minSearchLength($chars) Minimum characters before searching (default 2)
useShortLabels($enabled) Use short labels instead of full address (default false)
textMode($enabled) Return text only instead of coordinates (default false)

MapWidget

Method Description
getHeading() Returns the widget heading
getAutoCenter() Returns the auto-center setting
getMarkers() Returns array of markers to display
getShapes() Returns array of shapes to display
getLayers() Returns combined markers and shapes
onMapClick($lat, $lng) Handles map click events
onLayerClick($layerId) Handles layer click events
refreshMap() Manually refresh the map
afterMarkerCreated($record) Hook after marker creation
mutateFormDataBeforeCreate($data) Transform form data before save
$markerClickAction Define action for marker clicks (view/edit/delete)
$markerModel Eloquent model class for markers (enables CRUD)
$markerResource Optional Filament Resource for marker actions
$coordinatesColumnName Optional Column name for coordinates in CRUD (null uses config default)

MapPicker

Method Description
make($name) Create a new MapPicker field
followMarker() Pan to the marker when the field coordinates change, keeping the current zoom. Disabled by default.
autoCenter(bool) Auto-center map to user's current location
center($lat, $lng) Set map center coordinates
zoom($level) Set initial zoom level
height($pixels) Set map height
mapDraggable($bool) Enable/disable map dragging
mapZoomable($bool) Enable/disable map zooming
static() Disable all map interactions (dragging & zooming)
recenterTimeout($milliseconds) Auto-recenter map after X ms of inactivity
tileLayersUrl($layers) Set tile layer(s)
markers($array) Set initial markers
shapes($array) Set initial shapes
boundaries($array) Set Boundary layers
pickMarker($marker) Customize the temporary marker shown on click
onMapClick($callback) Handle map click events with closure callback
onLayerClick($callback) Handle layer click events with closure callback
handleMapClick($lat, $lng) Exposed Livewire method for map clicks
handleLayerClick($layerId) Exposed Livewire method for layer clicks

MapEntry

Method Description
make($name) Create a new MapEntry entry
autoCenter(bool) Auto-center map to user's current location
center($lat, $lng) Set map center coordinates
zoom($level) Set initial zoom level
height($pixels) Set map height
mapDraggable($bool) Enable/disable map dragging
mapZoomable($bool) Enable/disable map zooming
static() Disable all map interactions (dragging & zooming)
recenterTimeout($milliseconds) Auto-recenter map after X ms of inactivity
tileLayersUrl($layers) Set tile layer(s)
markers($array) Set initial markers
shapes($array) Set initial shapes
boundaries($array) Set Boundary layers
pickMarker($marker) Customize the temporary marker shown on click
onMapClick($callback) Handle map click events with closure callback
onLayerClick($callback) Handle layer click events with closure callback

MapColumn

Method Description
make($name) Create a new MapColumn column
autoCenter(bool) Auto-center map to user's current location
center($lat, $lng) Set map center coordinates
zoom($level) Set initial zoom level
height($pixels) Set map height
circular($value) Display map as circular container
mapDraggable($bool) Enable/disable map dragging
mapZoomable($bool) Enable/disable map zooming
static() Disable all map interactions (dragging & zooming)
recenterTimeout($milliseconds) Auto-recenter map after X ms of inactivity
tileLayersUrl($layers) Set tile layer(s)
markers($array) Set initial markers
shapes($array) Set initial shapes
boundaries($array) Set Boundary layers
pickMarker($marker) Customize the temporary marker shown on click
onMapClick($callback) Handle map click events with closure callback
onLayerClick($callback) Handle layer click events with closure callback

Marker

Method Description
make($lat, $lng) Create a new marker
fromRecord() Create marker from Eloquent model
id($id) Set marker ID
title($title) Set title (tooltip & popup)
color($color) Set marker color
icon($icon, $size) Set custom icon URL or Heroicon
iconUrl($url) Set custom icon URL
iconSize($size) Set icon size as [width, height]
heroicon($icon) Set Heroicon (string or Heroicon enum)
draggable($bool) Make marker draggable
editable($bool) Make marker editable on the map
group($group) Assign to group (string or BaseLayerGroup)
popup($content, $fields, $options) Configure popup
tooltip($content, $permanent, $direction, $options) Configure tooltip
action($callback) Set click handler
distanceTo($marker) Calculate distance to another marker
validate() Validate coordinates

Shape (All Shapes)

Method Description
color($color) Set border color
fillColor($color) Set fill color
weight($pixels) Set border width
opacity($value) Set border opacity (0-1)
fillOpacity($value) Set fill opacity (0-1)
dashArray($pattern) Set dash pattern
editable($bool) Make shape editable on the map
popup($content, $fields, $options) Configure popup
tooltip($content, $permanent, $direction, $options) Configure tooltip
action($callback) Set click handler
group($group) Assign to group (string or BaseLayerGroup)
getCoordinates() Get center coordinates of the shape

Circle

Method Description
make($lat, $lng) Create circle
radius($meters) Set radius in meters
radiusInMeters($meters) Set radius in meters
radiusInKilometers($km) Set radius in kilometers
radiusInMiles($miles) Set radius in miles
radiusInFeet($feet) Set radius in feet

CircleMarker

Method Description
make($lat, $lng) Create circle marker
radius($pixels) Set radius in pixels

Polygon & Polyline

Method Description
make($coordinates) Create with coordinates
addPoint($lat, $lng) Add vertex/point

Polyline

Method Description
smoothFactor($factor) Set line smoothing

Rectangle

Method Description
make($corner1, $corner2) Create with corners
makeFromCoordinates($lat1, $lng1, $lat2, $lng2) Create with coordinates

Layer Group (Base)

Method Description
make($layers) Create layer group with layers
id($id) Set group ID
name($name) Set group name
option($key, $value) Set a group option
getLayers() Get all layers in the group

LayerGroup

Method Description
make($layers) Create simple layer group
name($name) Set user-visible group name
id($id) Set group ID for controls
editable($bool) Make all layers in group editable

FeatureGroup

Method Description
make($markers) Create feature group from markers
name($name) Set zone/area name
blue(), red(), etc. Set border color
fillBlue(), fillRed(), etc. Set fill color
fillOpacity($value) Set fill transparency (0-1)
weight($pixels) Set border width
editable($bool) Make all layers in group editable

MarkerCluster

Method Description
make($markers) Create cluster with markers
fromModel() Create cluster from Eloquent model
marker($marker) Add single marker
markers($array) Add multiple markers
name($name) Set cluster group name
editable($bool) Make all markers in cluster editable
maxClusterRadius($pixels) Set cluster radius (pixels)
showCoverageOnHover($bool) Show cluster coverage on hover
zoomToBoundsOnClick($bool) Zoom to bounds when clicked
spiderfyOnMaxZoom($bool) Spread markers at max zoom
disableClusteringAtZoom($level) Disable clustering at zoom level
animate($bool) Animate cluster changes
modifyQueryUsing($callback) Modify database query
mapRecordUsing($callback) Customize each marker

Color Reference

Markers and shapes accept colors from multiple sources:

Tile Layer Reference

Available tile layer providers:

  • TileLayer::OpenStreetMap - Free, open-source map tile provider
  • TileLayer::GoogleStreets - Google Maps street view tiles
  • TileLayer::GoogleSatellite - Google Maps satellite imagery tiles
  • TileLayer::GoogleHybrid - Google Maps hybrid tiles (satellite + labels)
  • TileLayer::GoogleTerrain - Google Maps terrain tiles
  • TileLayer::EsriWorldImagery - Esri World Imagery tiles
  • TileLayer::EsriWorldStreetMap - Esri World Street Map tiles
  • TileLayer::EsriNatGeo - Esri National Geographic tiles
  • TileLayer::CartoPositron - Carto Positron tiles
  • TileLayer::CartoDarkMatter - Carto Dark Matter tiles
  • TileLayer::MapboxStreets - Mapbox Streets tiles
  • TileLayer::MapboxOutdoors - Mapbox Outdoors tiles
  • TileLayer::MapboxLight - Mapbox Light tiles
  • TileLayer::MapboxDark - Mapbox Dark tiles
  • TileLayer::MapboxSatellite - Mapbox Satellite tiles
  • TileLayer::MapboxSatelliteStreets - Mapbox Satellite Streets tiles
  • TileLayer::MapboxNavigationDay - Mapbox Navigation Day tiles
  • TileLayer::MapboxNavigationNight - Mapbox Navigation Night tiles

Value Objects Reference

Coordinate

The Coordinate value object represents a geographical point with latitude and longitude coordinates. It's used throughout the package for storing and manipulating map coordinates.

Storage Modes:

The Coordinate cast supports two storage modes:

  1. JSON Column - Store coordinates as JSON in a single column
  2. Virtual Attribute - Manage separate latitude and longitude columns automatically

Usage in Models - JSON Column:

use EduardoRibeiroDev\FilamentLeaflet\ValueObjects\Coordinate;

class Location extends Model
{
    protected $casts = [
        'coordinates' => Coordinate::class,  // Stores as { "lat": -23.5505, "lng": -46.6333 }
    ];
}

// Usage
$location = Location::first();
echo $location->coordinates->lat;  // -23.5505
echo $location->coordinates->lng;  // -46.6333

Usage in Models - Virtual Attribute (Separate Columns):

If you have separate latitude and longitude columns, use the cast with column parameters:

use EduardoRibeiroDev\FilamentLeaflet\ValueObjects\Coordinate;

class Store extends Model
{
    protected $casts = [
        // Maps to latitude and longitude columns
        'location' => Coordinate::class,
    ];
}

// Usage
$store = Store::first();
echo $store->location->lat;   // Reads from 'latitude' column
echo $store->location->lng;   // Reads from 'longitude' column

Practical Example - Virtual Attribute:

// Migration
Schema::create('stores', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->decimal('latitude', 10, 8);      // Stores lat
    $table->decimal('longitude', 11, 8);     // Stores lng
    $table->timestamps();
});

// Model
class Store extends Model
{
    protected $casts = [
        'location' => Coordinate::class . ':latitude,longitude', // If the lat/lng columns don't follow the config default names, specify them here
    ];
}

Basic Usage:

$store1 = Store::first();
$store2 = Store::find(2);

echo $store1->location->lat;  // Access latitude
echo $store1->location->lng;  // Access longitude

$distance = $store1->location->distanceTo($store2->location); // Calculate distance in kilometers
$store1->toArray(); // ['lat' => -23.5505, 'lng' => -46.6333]
$store1->toFlatArray(); // [-23.5505, -46.6333]

$store1->location = new Coordinate(-23.5505, -46.6333); // Update location
$store1->save();

Methods:

Method Description
__construct($lat, $lng) Create a new Coordinate instance
toArray() Convert to associative array with 'lat' and 'lng' keys
toFlatArray() Convert to flat array [$lat, $lng]
fromArray($array) Create from array with 'lat'/'lng' or numeric keys
fromObject($object) Create from object with lat/lng properties
from($coordinates) Universal factory method for arrays, objects, or Coordinate instances
distanceTo($other) Calculate distance to another Coordinate (in kilometers)
castUsing() Internal method for configuring Eloquent casting

GeoSearchResult

The GeoSearchResult value object represents a geocoding search result with complete location information from geocoding providers.

Properties:

$result->coordinate;   // Coordinate object with lat/lng
$result->name;         // Short place name (e.g., "São Paulo")
$result->displayName;  // Full formatted address
$result->type;         // Location type (building, street, city, etc.)
$result->addresstype;  // Address classification
$result->address;      // Address value object with detailed components
$result->boundingbox;  // Geographic bounds [minLat, minLng, maxLat, maxLng]

Address

The Address value object contains structured address information from geocoding results.

Properties:

Property Type Description
suburb string|null Suburb or neighborhood name
cityDistrict string|null City district
city string|null City name (town, village)
county string|null County name
state string|null State or province
province string|null Province name
region string|null Region name
postcode string|null Postal code
country string|null Country name
countryCode string|null ISO 3166-1 country code

Concern Methods Reference

Boundary

Method Description
fromUrl($url) Load GeoJSON from a public URL
fromStorage($path, $disk) Load GeoJSON from Laravel storage
fromGeoJson($data) Render an inline GeoJSON object
features($key, $label) Select feature properties used for joins and labels
values($values) Join thematic values to features
colorScale($colors, $missingColor) Configure choropleth colors
choropleth($values, $colors, $missingColor) Configure values and colors together

Administrative layers use AdministrativeBoundary.

Method Description
restrictTo($regions) Restrict the territory using one shapeID, a list of shapeIDs, or a closure; pass null to clear
values($values) Accept shapeID totals, a list of shapeID-to-value maps, or a closure
level($level) Select a fixed AdministrativeLevel enum or Auto, optionally through a closure

Generated classes in Countries are static ID helpers. country(), state($code) and city($state, $name) return strings. states($values) and cities($state, $values) return arrays keyed by shapeID. All layer methods belong to AdministrativeBoundary.

Map Configuration Properties

These properties control core map behavior:

Property Type Default Description
$mapCenter array null Initial map center [latitude, longitude] (null uses config default)
$autoCenter bool false Auto-center to user's current location on load
$defaultZoom int 4 Initial zoom level
$mapHeight int 598 Map height in pixels
$mapDraggable bool true Allow users to pan by dragging
$mapZoomable bool true Allow users to zoom (scroll wheel, pinch)
$recenterMapTimeout ?int null Auto-recenter after X milliseconds of panning
$maxZoom int 19 Maximum zoom level allowed
$minZoom int 2 Minimum zoom level allowed
$hasDrawMarkerControl bool false Show draw marker control
$hasDrawCircleMarkerControl bool false Show draw circle marker toolbar
$hasDrawCircleControl bool false Show draw circle toolbar
$hasDrawPolylineControl bool false Show draw polyline toolbar
$hasDrawRectangleControl bool false Show draw rectangle toolbar
$hasDrawPolygonControl bool false Show draw polygon toolbar
$hasDrawTextControl bool false Show draw text toolbar
$hasEditLayersControl bool false Show edit layers toolbar
$hasDragLayersControl bool false Show drag layers toolbar
$hasRemoveLayersControl bool false Show remove layers toolbar
$hasRotateLayersControl bool false Show rotate layers toolbar
$hasCutPolygonControl bool false Show cut polygon toolbar
$hasFullscreenControl bool false Show fullscreen button
$hasSearchControl bool false Show address search
$hasScaleControl bool false Show distance scale
$hasZoomControl bool true Show zoom +/- buttons
$hasAttributionControl bool false Show attribution text
$tileLayersUrl mixed OpenStreetMap Base map tile layers

License

This package is open-sourced software licensed under the MIT license. Check the LICENSE file for more information.

Credits

Support

For issues, questions, or contributions, please visit the GitHub repository. Don't forget, Jesus loves you ❤️.