Download the PHP package eduardoribeirodev/filament-leaflet without Composer

Filament Leaflet

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 - Render density maps with custom color schemes and automatically load spatial data using the HasGeoJsonFile model trait.
• 🔍 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.

Table of Contents

• Installation
• Configuration
• Core Components
  • Map Widget
  • MapPicker (Form Field)
  • GeoSearchInput (Form Field)
  • MapColumn (Table Column)
  • MapEntry (Infolist)
• Map Elements
  • Markers
  • Layer Groups
  • Shapes
  • Editable Layers
• User Interactions
• Advanced Features
• Best Practices
• Configuration Reference
  • Method Reference
  • Concern Methods Reference

Installation

Publish the assets:

This will publish the Leaflet assets used by the package.

Configuration

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

Publish the configuration file:

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

Core Components

Map Widget

Create your first interactive map widget:

Basic Configuration

Map Interaction Control

Control how users interact with your map:

Static Maps - Disable all interactions:

Controls

Enable/disable map controls:

Conditionally show controls at runtime:

Tile Layers

Choose from multiple providers or add custom layers:

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:

MapPicker (Form Field)

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

Load GeoJSON: Automatically loads from models with HasGeoJsonFile trait or getGeoJsonUrl() method:

Customize pick marker: Visual feedback when clicking the map:

Dynamic configuration: Most methods accept closures:

GeoSearchInput (Form Field)

Search and select locations using multiple geocoding providers:

Advanced Configuration:

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:

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

Address Components:

The Address object provides structured address data:

MapColumn (Table Column)

Display maps directly in Filament table columns:

Display circular maps for a unique visual style:

MapEntry (Infolist)

Display read-only maps in Filament infolists:

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

Map Elements

Markers

Creating Markers

Marker Icons

Markers support multiple icon types with different visual behaviors:

Custom Icon URL (replaces the entire marker):

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):

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:

Using string formats:

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

From Eloquent Models

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

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:

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:

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:

Marker Cluster

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

Cluster from Model:

Create clusters directly from Eloquent models with powerful customization:

Cluster with Query Modification:

Filter and customize the query used to load markers:

Advanced cluster configuration:

Shapes

Draw various geometric shapes on your map:

Circles

Circles with radius in various units:

Circle Markers

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

Polygons

Draw custom polygons:

Polylines

Draw lines connecting multiple points:

Rectangles

Draw rectangular bounds:

Shapes from Eloquent Models

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

Configure Your Model:

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

Polygon from Record

Polyline from Record

Rectangle from Record

Shape Styling

Editable Layers

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

You can also make all layers in a group editable:

User Interactions

Popups and Tooltips

Tooltips (appear on hover)

Popups (appear on click)

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

Click Actions

Marker Click Handler

Shape Click Handler

From Model Records

Map Click Handler

Handle clicks on the map itself:

Field/Entry/Column Click Handlers

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

Handle layer (marker/shape) clicks:

Advanced Features

Model Integration & CRUD Operations

Enable creating markers directly from map clicks:

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:

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:

Hooks:

Keep Maps in Sync with Tables:

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

GeoJSON Density Maps

Display choropleth maps with custom density data:

Colors are automatically applied based on data distribution.

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).

All draw control labels, tooltips, and messages are automatically translated based on your application's locale.

To customize translations:

Then edit files in lang/vendor/filament-leaflet.

Best Practices

Performance Optimization

1. Use Marker Clusters for large datasets:

2. Limit data with query modifications:

3. Use appropriate zoom levels:

Debugging

Enable logging for map interactions:

Configuration Reference

Customization

Custom Styles

Add custom CSS to your map:

Custom Scripts

Execute JavaScript after map initialization:

Method Reference

GeoSearchInput

MapWidget

MapPicker

MapEntry

MapColumn

Marker

Shape (All Shapes)

Circle

CircleMarker

Polygon & Polyline

Polyline

Rectangle

Layer Group (Base)

LayerGroup

FeatureGroup

MarkerCluster

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:

Usage in Models - Virtual Attribute (Separate Columns):

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

Practical Example - Virtual Attribute:

Basic Usage:

Methods:

GeoSearchResult

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

Properties:

Address

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

Properties:

Concern Methods Reference

HasGeoJsonFile

Map Configuration Properties

These properties control core map behavior:

License

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

Credits

• Built for Filament
• Uses Leaflet for mapping
• Created by Eduardo Ribeiro

Support

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