Download the PHP package darkclow4/filament-map-picker without Composer

Filament Map Picker

filament-map-picker provides Filament 5 form, infolist, and widget components powered by Leaflet.js. Use it to select a point location in forms, draw one or more map areas as GeoJSON, and display saved locations in read-only infolists or dashboard widgets.

The package is designed to stay flexible. It does not force how you persist latitude, longitude, or area data. Instead, it keeps a predictable field state and lets you map the values however you want through afterStateUpdated() and afterStateHydrated().

Features

• Built for Filament 5
• Powered by locally bundled Leaflet.js and Leaflet Draw
• Form field, infolist entry, and dashboard widget APIs
• Default OpenStreetMap tile layer
• Custom tile support through ->tiles([...])
• drag mode and click mode for the point marker
• Optional geocoding search UI
• Optional polygon, rectangle, and circle drawing tools
• Optional multi-shape GeoJSON collections
• Combined point + area state in a single field
• Reactive Livewire-friendly state updates
• Alpine.js powered interaction
• Leaflet layers control for switching tile layers
• Read-only map rendering for detail pages and dashboards

Requirements

• PHP 8.3+
• Laravel 13+
• Filament 5

Installation

Install the package with Composer:

Then publish Filament assets:

Package Registration

The package supports Laravel auto-discovery through:

In most applications, no manual provider registration is needed.

State Format

Point-only mode

By default, the field stores point coordinates as:

Point + draw mode

When draw mode is enabled, the field stores a combined state:

This makes it easy to keep a marker location and one or more service-area shapes in the same field while still saving them into separate database columns.

Basic Usage

Point-only form field

Point + area in a single field

Read-only infolist entry

Use MapEntry when you want to display saved coordinates on view/detail pages.

Add ->interactive() if you want the user to pan and zoom around the point without changing the saved state.

For saved GeoJSON areas, enable ->drawable() and include geojson in the state:

Dashboard map widget

Use MapWidget directly when the state is passed from a page or dashboard:

For dynamic configuration, create your own widget class and extend the package widget:

Selection Modes

Drag mode

• the user drags the map
• the marker stays centered
• coordinates are taken from the map center

Click mode

• the user clicks on the map
• the marker moves to the clicked point
• coordinates are taken from that point

Default Tile Layer

If you do not provide custom tiles, the field uses OpenStreetMap automatically.

Built-in default tile definition:

Custom Tile Layers

You can provide your own tile layers with ->tiles([...]). Those definitions are serialized to JSON and passed directly to Leaflet.

Tile behavior:

• if ->tiles() is not called, only osm is available
• if ->tile() is not called, osm is selected by default
• if the selected tile key is invalid, the field falls back to osm
• if more than one base layer exists, Leaflet's built-in layers control is shown on the map
• by default the built-in osm tile is always included
• use ->showDefaultTile(false) if you want to hide the built-in osm tile and only expose your custom tiles

Searchable Mode

Enable geocoding search when you want users to jump quickly to a location:

Behavior:

• users can search for a place or address
• matching results appear in a dropdown list
• selecting a result recenters the map and updates the field state
• selected results are highlighted when reopened

By default, search uses:

You can override it:

Drawing Shapes as GeoJSON

Enable draw mode when you want the user to define areas while keeping a marker location in the same field state.

Notes:

• draw mode stores the field state as ['lat', 'lng', 'geojson']
• the marker location still works as normal
• the drawn area is stored inside geojson
• by default only one drawn shape is kept at a time
• use ->multipleShapes() if you want multiple polygons / rectangles / circles in the same FeatureCollection
• editing or deleting shapes updates the field state automatically
• use afterStateUpdated() / afterStateHydrated() to map latitude, longitude, and geojson into separate database columns

API Reference

Unless noted otherwise, these configuration methods are available on:

• Darkclow4\FilamentMapPicker\Forms\Components\MapPicker
• Darkclow4\FilamentMapPicker\Infolists\Components\MapEntry
• Darkclow4\FilamentMapPicker\Widgets\MapWidget

->tile(string $tile)

Sets the active tile key.

->tiles(array $tiles)

Registers custom tile layers.

Expected tile format:

->showDefaultTile(bool $condition = true)

Controls whether the built-in osm tile should be included in the available tile list.

->interactive(bool $condition = true)

Allows a read-only map to remain draggable and zoomable without syncing state back to Livewire.

->mode('drag|click')

Defines the point marker interaction mode.

->defaultLocation(float $lat, float $lng)

Sets the initial map coordinates.

->zoom(int $level)

Sets the initial map zoom level.

->height(int|string $height)

Sets the map container height.

->markerColor(string $color)

Sets the marker color used in both drag and click modes.

->searchable(bool $condition = true)

Enables place search. This is only available on the form field.

->searchPlaceholder(string $placeholder)

Overrides the search input placeholder.

->searchProviderUrl(string $url)

Overrides the geocoding endpoint used by the search box.

->searchResultLimit(int $limit)

Controls how many search results are shown in the dropdown.

->drawable(bool $condition = true)

Enables shape drawing tools and switches the field state into combined point + GeoJSON mode.

->drawTools(array $tools)

Controls which draw tools are available. Supported values are polygon, rectangle, and circle.

->fitDrawBounds(bool $condition = true)

Controls whether the map should automatically fit to the drawn shapes after create or edit.

->multipleShapes(bool $condition = true)

Allows the field to keep multiple drawn shapes inside the GeoJSON FeatureCollection.

->showAreaMeasurement(bool $condition = true)

Shows area labels directly inside the map for each drawn shape when draw mode is enabled.

->areaMeasurementUnit('m2'|'ha')

Controls the unit used for the displayed area measurement.

Notes

• The package does not force any persistence strategy for latitude, longitude, or area GeoJSON
• You are free to map the field state into any schema structure you prefer
• Custom tiles are the developer's responsibility, including availability and usage terms
• Search providers are the developer's responsibility, including availability and usage terms

License

This package is open-sourced software licensed under the MIT license.