Filament Map Picker

https://github.com/dotswan/filament-map-picker
Admin
Filament Map Picker is a custom field for Filament that allows you to select a location on a map and...
Tokens:11,013
Snippets:83
Trust Score:7.7
License:MIT
Update:2 months ago
Show doc for...
Tokens:
Raw
### Install Filament Map Picker (General)

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Install the package via Composer. This command is for general installation and may apply to versions prior to v3.

```bash
composer require dotswan/filament-map-picker
```

--------------------------------

### Install Filament Map Picker

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Install the package using Composer. Use the specified version for Filament v3 (legacy).

```bash
# Filament v4 / v5
composer require dotswan/filament-map-picker
```

```bash
# Filament v3 (legacy)
composer require dotswan/filament-map-picker:"^1.8"
```

--------------------------------

### Install Filament Map Picker for Filament v3

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Use this command to install the package for Filament v3. Ensure you are using compatible versions of PHP and Filament.

```bash
composer require dotswan/filament-map-picker:"^1.8"
```

--------------------------------

### Set Initial Marker Position with defaultLocation()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Configure the initial latitude and longitude for the map marker and center using the `defaultLocation()` method. This sets the starting point when the field first renders.

```php
Map::make('location')
    ->defaultLocation(latitude: 51.5074, longitude: -0.1278)  // London
    ->zoom(12)
    ->showMarker(true)
```

--------------------------------

### Enable Live Location Updates

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Configure live location tracking with options to send user location, send in real-time, and set update intervals.

```php
Map::make('location')
    ->liveLocation(true, true, 10000)  // Updates live location every 10 seconds
    ->showMarker()
    ->draggable()
```

--------------------------------

### Configure MapEntry as Infolist Field

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Displays a map in an infolist with various configuration options for appearance and behavior. Use this to show map data in a read-only context.

```php
use Dotswan\MapPicker\Infolists\MapEntry;

public static function infolist(Infolist $infolist):
 Infolist
{
    return $infolist
        ->schema([
            MapEntry::make('location')
                // Dynamic Location from Record
                ->defaultLocation(
                    latitude: fn ($record) => $record?->latitude ?? 0,
                    longitude: fn ($record) => $record?->longitude ?? 0
                )
                
                // Basic Configuration
                ->draggable(false)
                ->zoom(15)
                ->minZoom(0)
                ->maxZoom(28)
                ->tilesUrl("https://tile.openstreetmap.de/{z}/{x}/{y}.png")
                ->detectRetina(true)
                
                // Marker Configuration
                ->showMarker(true)
                ->markerColor("#22c55eff")
                ->markerHtml('<div class="custom-marker">...</div>')
                ->markerIconUrl('/path/to/marker.png')
                ->markerIconSize([36, 36])
                ->markerIconClassName('my-marker-class')
                ->markerIconAnchor([18, 36])
                
                // Controls
                ->showFullscreenControl(true)
                ->showZoomControl(true)
                
                // GeoMan Integration (if needed for viewing)
                ->geoMan(true)
                ->geoManEditable(false)
                ->geoManPosition('topleft')
                ->drawCircleMarker(true)
                ->drawMarker(true)
                ->drawPolygon(true)
                ->drawPolyline(true)
                ->drawCircle(true)
                ->drawRectangle(true)
                ->drawText(true)
                
                // Styling
                ->extraStyles([
                    'min-height: 50vh',
                    'border-radius: 8px'
                ])
        ]);
}
```

--------------------------------

### Use Custom Tile Layers

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Replace default map tiles by specifying a custom XYZ tile server URL with `tilesUrl()`. `extraTileControl()` can be used for additional layer options, and `detectRetina()` improves rendering on high-DPI displays.

```php
Map::make('location')
    ->tilesUrl('https://{s}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png')
    ->extraTileControl(['subdomains' => 'abc'])
    ->detectRetina(true)
    ->zoom(13)
```

--------------------------------

### Enable Click-to-Place Marker with clickable()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Allow users to place the marker by clicking on the map instead of dragging. Use `clickable(true)` and optionally `draggable(false)` to lock panning.

```php
Map::make('location')
    ->defaultLocation(latitude: 48.8566, longitude: 2.3522)   // Paris
    ->clickable(true)
    ->draggable(false)   // lock panning; user clicks to choose
    ->zoom(14)
    ->showMarker(true)
```

--------------------------------

### Define Database Schema for Map Coordinates

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Sets up the necessary database columns for storing latitude and longitude values. Ensure these columns are nullable if locations are optional.

```php
$table->double('latitude')->nullable();
$table->double('longitude')->nullable();
```

--------------------------------

### Control Map Zoom Levels and Controls

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Configure map zoom behavior with `zoom()` for the initial level, `minZoom()` and `maxZoom()` to set the allowed range, and `showZoomControl()` and `showFullscreenControl()` to toggle UI elements. `detectRetina()` enhances display on high-resolution screens.

```php
Map::make('location')
    ->zoom(15)          // initial zoom
    ->minZoom(3)        // prevent zooming out further than continents
    ->maxZoom(19)       // cap at street level
    ->showZoomControl(true)
    ->showFullscreenControl(true)
    ->detectRetina(true)
```

--------------------------------

### Enable Real-Time GPS Updates with liveLocation()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Stream the browser's Geolocation API to the server for real-time GPS updates. Configure sending, polling, and interval using `$send`, `$realtime`, and `$milliseconds` parameters.

```php
Map::make('location')
    ->liveLocation(
        send: true,
        realtime: true,
        miliseconds: 10000   // push GPS coordinates every 10 s
    )
    ->showMyLocationButton(true)
    ->showMarker(true)
    ->draggable(true)
```

--------------------------------

### Display Map in Filament Infolist

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Use MapEntry::make() to display a read-only map in a Filament infolist. Coordinates are loaded from the Eloquent record using closures.

```php
<?php

use Dotswan\MapPicker\Infolists\MapEntry;
use Filament\Infolists\Infolist;

public static function infolist(Infolist $infolist): Infolist
{
    return $infolist->schema([
        MapEntry::make('location')
            // Load coordinates from the Eloquent record
            ->defaultLocation(
                latitude:  fn ($record) => $record?->latitude  ?? 0,
                longitude: fn ($record) => $record?->longitude ?? 0
            )
            ->draggable(false)         // read-only map
            ->zoom(15)
            ->tilesUrl('https://tile.openstreetmap.de/{z}/{x}/{y}.png')
            ->detectRetina(true)
            ->showMarker(true)
            ->markerColor('#22c55e')
            ->showFullscreenControl(true)
            ->extraStyles(['min-height: 40vh', 'border-radius: 8px']),
    ]);
}
```

--------------------------------

### liveLocation()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Streams the browser's Geolocation API to the server for real-time GPS updates.

```APIDOC
## liveLocation()

### Description
Streams the browser's Geolocation API to the server. Accepts three parameters: `$send` (enable), `$realtime` (poll repeatedly), and `$milliseconds` (polling interval).

### Method
`liveLocation(bool $send = true, bool $realtime = false, int $miliseconds = 10000)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
Map::make('location')
    ->liveLocation(
        send: true,
        realtime: true,
        miliseconds: 10000   // push GPS coordinates every 10 s
    )
    ->showMyLocationButton(true)
    ->showMarker(true)
    ->draggable(true)
```

### Response
#### Success Response (200)
Returns the Map component instance for chaining.
```

--------------------------------

### Configure Map Picker Field in Filament Resource

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

This snippet shows the extensive configuration options for the Map::make('location') field within a Filament Resource's form schema. It covers basic settings, marker customization, controls, location features, GeoMan integration, and state management callbacks.

```php
<?php
namespace App\Filament\Resources;
use Filament\Resources\Resource;
use Filament\Resources\Forms\Form;
use Dotswan\MapPicker\Fields\Map;
...

class FilamentResource extends Resource
{
    ...
    public static function form(Form $form)
    {
        return $form->schema([
            Map::make('location')
                ->label('Location')
                ->columnSpanFull()
                // Basic Configuration
                ->defaultLocation(latitude: 40.4168, longitude: -3.7038)
                ->draggable(true)
                ->clickable(true) // click to move marker
                ->zoom(15)
                ->minZoom(0)
                ->maxZoom(28)
                ->tilesUrl("https://tile.openstreetmap.de/{z}/{x}/{y}.png")
                ->detectRetina(true)
                
                // Marker Configuration
                ->showMarker(true)
                ->markerColor("#3b82f6")
                ->markerHtml('<div class="custom-marker">...</div>')
                ->markerIconUrl('/path/to/marker.png')
                ->markerIconSize([36, 36])
                ->markerIconClassName('my-marker-class')
                ->markerIconAnchor([18, 36])
                
                // Controls
                ->showFullscreenControl(true)
                ->showZoomControl(true)
                
                // Location Features
                ->liveLocation(true, true, 5000)
                ->showMyLocationButton(true)
                ->boundaries(true, 49.5, -11, 61, 2) // Example for British Isles
                ->rangeSelectField('distance')
                
                // GeoMan Integration
                ->geoMan(true)
                ->geoManEditable(true)
                ->geoManPosition('topleft')
                ->drawCircleMarker(true)
                ->rotateMode(true)
                ->drawMarker(true)
                ->drawPolygon(true)
                ->drawPolyline(true)
                ->drawCircle(true)
                ->drawRectangle(true)
                ->drawText(true)
                ->dragMode(true)
                ->cutPolygon(true)
                ->editPolygon(true)
                ->deleteLayer(true)
                ->setColor('#3388ff')
                ->setFilledColor('#cad9ec')
                ->snappable(true, 20)
                
                // Extra Customization
                ->extraStyles([
                    'min-height: 150vh',
                    'border-radius: 50px'
                ])
                ->extraControl(['customControl' => true])
                ->extraTileControl(['customTileOption' => 'value'])
                
                // State Management
                ->afterStateUpdated(function (Set $set, ?array $state): void {
                    $set('latitude', $state['lat']);
                    $set('longitude', $state['lng']);
                    $set('geojson', json_encode($state['geojson']));
                })
                ->afterStateHydrated(function ($state, $record, Set $set): void {
                    $set('location', [
                        'lat' => $record->latitude,
                        'lng' => $record->longitude,
                        'geojson' => json_decode(strip_tags($record->description))
                    ]);
                })
        ]);
    }
    ...
}

```

--------------------------------

### Enable Click-to-Place Marker in Map Picker

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Configures the Map::make('location') field to allow users to place the marker by clicking on the map. This overrides the default behavior where the marker is centered as the map is dragged.

```php
Map::make('location')
  ->defaultLocation(latitude: 40.4168, longitude: -3.7038)
  ->showMarker(true)
  ->clickable(true)
  ->tilesUrl("https://tile.openstreetmap.de/{z}/{x}/{y}.png")
  ->zoom(12)
```

--------------------------------

### defaultLocation()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Sets the initial latitude and longitude for the map marker and centers the map when the field first renders.

```APIDOC
## defaultLocation()

### Description
Sets the latitude and longitude the marker and map are centered on when the field first renders.

### Method
`defaultLocation(float $latitude, float $longitude)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
Map::make('location')
    ->defaultLocation(latitude: 51.5074, longitude: -0.1278)  // London
    ->zoom(12)
    ->showMarker(true)
```

### Response
#### Success Response (200)
Returns the Map component instance for chaining.
```

--------------------------------

### clickable()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Enables click-to-place functionality, allowing users to move the marker by clicking on the map.

```APIDOC
## clickable()

### Description
When enabled, clicking anywhere on the map moves the marker to that point instead of requiring the user to drag the map underneath a fixed crosshair.

### Method
`clickable(bool $condition = true)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
Map::make('location')
    ->defaultLocation(latitude: 48.8566, longitude: 2.3522)   // Paris
    ->clickable(true)
    ->draggable(false)   // lock panning; user clicks to choose
    ->zoom(14)
    ->showMarker(true)
```

### Response
#### Success Response (200)
Returns the Map component instance for chaining.
```

--------------------------------

### Custom Tile Layers

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Enables the use of custom XYZ tile providers for the map.

```APIDOC
## Custom Tile Layers

### Description
Swap the default OpenStreetMap tile server with any compatible XYZ tile provider.

### Methods
- `tilesUrl(string $url)`
- `extraTileControl(array $options)`

### Request Example
```php
Map::make('location')
    ->tilesUrl('https://{s}.tile.openstreetmap.fr/hot/{z}/{x}/{y}.png')
    ->extraTileControl(['subdomains' => 'abc'])
    ->detectRetina(true)
    ->zoom(13)
```
```

--------------------------------

### Configure Map Form Field

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Use the `Map::make()` method to add an interactive map to your Filament forms. The field state is updated with coordinates on marker move or map click. Configure map behavior, appearance, and event handlers.

```php
<?php

namespace App\Filament\Resources;

use Filament\Forms\Components\Hidden;
use Filament\Forms\Components\TextInput;
use Filament\Forms\Form;
use Filament\Forms\Set;
use Filament\Resources\Resource;
use Dotswan\MapPicker\Fields\Map;

class LocationResource extends Resource
{
    public static function form(Form $form): Form
    {
        return $form->schema([
            Map::make('location')
                ->label('Pick a Location')
                ->columnSpanFull()
                ->defaultLocation(latitude: 40.4168, longitude: -3.7038)  // Madrid
                ->draggable(true)
                ->clickable(true)           // click map to move marker
                ->zoom(13)
                ->minZoom(5)
                ->maxZoom(18)
                ->tilesUrl('https://tile.openstreetmap.de/{z}/{x}/{y}.png')
                ->detectRetina(true)
                ->showMarker(true)
                ->markerColor('#e11d48')
                ->showZoomControl(true)
                ->showFullscreenControl(true)
                ->extraStyles(['min-height: 60vh', 'border-radius: 12px'])
                ->afterStateUpdated(function (Set $set, ?array $state): void {
                    // Sync lat/lng hidden fields whenever the marker moves
                    $set('latitude',  $state['lat']  ?? null);
                    $set('longitude', $state['lng']  ?? null);
                })
                ->afterStateHydrated(function ($state, $record, Set $set): void {
                    // Restore marker position when editing an existing record
                    if ($record) {
                        $set('location', [
                            'lat' => $record->latitude,
                            'lng' => $record->longitude,
                        ]);
                    }
                }),

            TextInput::make('latitude')->readOnly()->hiddenLabel(),
            TextInput::make('longitude')->readOnly()->hiddenLabel(),
        ]);
    }
}
```

--------------------------------

### Enable Drawing and Editing with GeoMan

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Integrate GeoMan for drawing and editing vector geometries on the map. Configure tools like `drawMarker()`, `editPolygon()`, and `dragMode()`. The map state returns GeoJSON, and colors can be set with `setColor()` and `setFilledColor()`. Use `afterStateUpdated()` to process the GeoJSON state.

```php
Map::make('location')
    ->geoMan(true)
    ->geoManEditable(true)
    ->geoManPosition('topleft')    // 'topleft' | 'topright' | 'bottomleft' | 'bottomright'
    // Drawing tools
    ->drawMarker(true)
    ->drawPolygon(true)
    ->drawPolyline(true)
    ->drawCircle(true)
    ->drawCircleMarker(true)
    ->drawRectangle(true)
    ->drawText(true)
    // Editing tools
    ->editPolygon(true)
    ->cutPolygon(true)
    ->dragMode(true)
    ->rotateMode(true)
    ->deleteLayer(true)
    // Snapping
    ->snappable(true, 20)          // snap threshold in pixels
    // Colors
    ->setColor('#2563eb')          // stroke color
    ->setFilledColor('#bfdbfe')    // fill color
    ->afterStateUpdated(function (Set $set, ?array $state): void {
        $set('geojson', json_encode($state['geojson'] ?? null));
    })
```

--------------------------------

### Constrain Map Pan Area with boundaries()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Use the `boundaries()` method to restrict map panning to a specific geographic bounding box. This ensures the user stays within a defined area. The `setBoundsToBritishIsles()` method offers a convenient alias for a predefined bounding box.

```php
Map::make('location')
    ->boundaries(true, 49.5, -11.0, 61.0, 2.0)  // SW lat, SW lng, NE lat, NE lng
    ->minZoom(6)
    ->showZoomControl(true)
    ->showMarker(true)
```

```php
// Convenience alias for the same bounding box
Map::make('location')
    ->setBoundsToBritishIsles()
    ->minZoom(6)
```

--------------------------------

### Programmatically Refresh Map via Livewire Event

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Trigger a map re-render by dispatching the `refreshMap` browser event from Livewire. This is useful after updating map coordinates programmatically, such as from an action button. Ensure the `location`, `latitude`, and `longitude` states are set before dispatching the event.

```php
use Filament\Forms\Components\Actions;
use Filament\Forms\Components\Actions\Action;
use Filament\Support\Enums\VerticalAlignment;

Actions::make([
    Action::make('Use Headquarters')
        ->icon('heroicon-m-map-pin')
        ->action(function (Set $set, $livewire): void {
            $lat = 52.3676;
            $lng = 4.9041;

            $set('location',  ['lat' => $lat, 'lng' => $lng]);
            $set('latitude',  $lat);
            $set('longitude', $lng);

            // Tell the Alpine/Leaflet component to re-draw
            $livewire->dispatch('refreshMap');
        })
])->verticalAlignment(VerticalAlignment::Start)
```

--------------------------------

### Refresh Map Action in Filament

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Demonstrates how to create a Filament Form Action that updates the map's location and dispatches a 'refreshMap' event to update the map component. This is useful for programmatically changing the map's center or marker.

```php
use Filament\Forms\Components\Actions\Action;
use Filament\Forms\Components\Actions;
use Filament\Support\Enums\VerticalAlignment;

Actions::make([
    Action::make('Set Default Location')
        ->icon('heroicon-m-map-pin')
        ->action(function (Set $set, $state, $livewire): void {
            $set('location', ['lat' => '52.35510989541003', 'lng' => '4.883422851562501']);
            $set('latitude', '52.35510989541003');
            $set('longitude', '4.883422851562501');
            $livewire->dispatch('refreshMap');
        })
])->verticalAlignment(VerticalAlignment::Start);
```

--------------------------------

### Programmatic Map Refresh via Livewire Event

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Triggers a map re-render using a Livewire event.

```APIDOC
## Programmatic Map Refresh via Livewire Event

### Description
Trigger a full map re-render (e.g., after setting coordinates from an action button) by dispatching the `refreshMap` browser event.

### Method
Dispatch the `refreshMap` browser event from Livewire.

### Request Example
```php
use Filament\
Forms\Components\Actions;
use Filament\nForms\Components\Actions\Action;
use Filament\nSupport\Enums\VerticalAlignment;

Actions::make([
    Action::make('Use Headquarters')
        ->icon('heroicon-m-map-pin')
        ->action(function (Set $set, $livewire): void {
            $lat = 52.3676;
            $lng = 4.9041;

            $set('location',  ['lat' => $lat, 'lng' => $lng]);
            $set('latitude',  $lat);
            $set('longitude', $lng);

            // Tell the Alpine/Leaflet component to re-draw
            $livewire->dispatch('refreshMap');
        })
])->verticalAlignment(VerticalAlignment::Start)
```
```

--------------------------------

### Set Map Boundaries

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Define map boundaries using southwest and northeast points to restrict panning. Ensure `minZoom` is set appropriately when using zoom controls.

```php
Map::make('location')
    ->showMarker()
    ->boundaries(true,49,11.1,61.0,2.1)
    ->draggable()
```

--------------------------------

### Zoom Controls

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Allows fine-grained control over the map's zoom level and UI controls.

```APIDOC
## Zoom Controls

### Description
Fine-grained control over initial zoom level, allowed zoom range, and which UI controls are shown.

### Methods
- `zoom(int $level)`
- `minZoom(int $level)`
- `maxZoom(int $level)`
- `showZoomControl(bool $show)`
- `showFullscreenControl(bool $show)`
- `detectRetina(bool $detect)`

### Request Example
```php
Map::make('location')
    ->zoom(15)          // initial zoom
    ->minZoom(3)        // prevent zooming out further than continents
    ->maxZoom(19)       // cap at street level
    ->showZoomControl(true)
    ->showFullscreenControl(true)
    ->detectRetina(true)
```
```

--------------------------------

### Marker Customization

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Provides options for customizing the appearance of the map marker.

```APIDOC
## Marker Customization

### Description
Full control over the marker's visual appearance via color, custom HTML div-icon, image URL, pixel size, CSS class, and anchor point.

### Methods
- `markerColor(string $color)`
- `markerHtml(string $html)`
- `markerIconUrl(string $url)`
- `markerIconSize(array $size)`
- `markerIconAnchor(array $anchor)`
- `markerIconClassName(string $className)`

### Request Example
```php
// Option A – color-tinted SVG marker
Map::make('location')
    ->showMarker(true)
    ->markerColor('#10b981')   // emerald-500

// Option B – custom HTML div-icon
Map::make('location')
    ->showMarker(true)
    ->markerHtml('<div class="pulse-dot" style="background:#f43f5e;width:16px;height:16px;border-radius:50%;"></div>')

// Option C – image icon with precise anchor
Map::make('location')
    ->showMarker(true)
    ->markerIconUrl('/img/map-pin.png')
    ->markerIconSize([48, 48])
    ->markerIconAnchor([24, 48])
    ->markerIconClassName('custom-pin')
```
```

--------------------------------

### Set Dynamic Default Location for MapEntry

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Configures the default latitude and longitude for a MapEntry using closures, allowing coordinates to be fetched dynamically from the current record. Useful for pre-populating map markers.

```php
MapEntry::make('location')
    ->defaultLocation(
        latitude: fn ($record) => $record?->latitude ?? 0,
        longitude: fn ($record) => $record?->longitude ?? 0
    )
```

--------------------------------

### Display GeoJSON Data on MapEntry

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Renders GeoJSON data on a MapEntry field, enabling the display of complex geographical shapes. Requires GeoMan to be enabled for rendering.

```php
MapEntry::make('location')
    ->defaultLocation(
        latitude: fn ($record) => $record?->latitude ?? 0,
        longitude: fn ($record) => $record?->longitude ?? 0
    )
    ->geojsonData(fn ($record) => $record?->geojson)
    ->geoMan(true)
    ->geoManEditable(false)
```

--------------------------------

### Database Migration for Location Data

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Defines the database schema for storing location data, including latitude, longitude, and GeoJSON. Ensure the 'geojson' column is of type JSON.

```php
// database/migrations/xxxx_xx_xx_create_locations_table.php
Schema::create('locations', function (Blueprint $table): void {
    $table->id();
    $table->double('latitude')->nullable();
    $table->double('longitude')->nullable();
    $table->json('geojson')->nullable();
    $table->timestamps();
});
```

--------------------------------

### Customize Map Marker Appearance

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Customize map markers using various options: `markerColor()` for tinted SVGs, `markerHtml()` for custom HTML div-icons, and `markerIconUrl()`, `markerIconSize()`, `markerIconAnchor()`, and `markerIconClassName()` for image-based icons with precise positioning.

```php
// Option A – color-tinted SVG marker
Map::make('location')
    ->showMarker(true)
    ->markerColor('#10b981')   // emerald-500
```

```php
// Option B – custom HTML div-icon
Map::make('location')
    ->showMarker(true)
    ->markerHtml('<div class="pulse-dot" style="background:#f43f5e;width:16px;height:16px;border-radius:50%;"></div>')
```

```php
// Option C – image icon with precise anchor
Map::make('location')
    ->showMarker(true)
    ->markerIconUrl('/img/map-pin.png')
    ->markerIconSize([48, 48])
    ->markerIconAnchor([24, 48])
    ->markerIconClassName('custom-pin')
```

--------------------------------

### Hydrate Map State from Record Coordinates

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Sets the map's state with latitude and longitude values retrieved from the current record after the component has been hydrated. This ensures the map displays the correct location on load.

```php
->afterStateHydrated(function ($state, $record, Set $set): void {
    $set('location', ['lat' => $record?->latitude, 'lng' => $record?->longitude]);
})
```

--------------------------------

### Display GeoJSON Data in Map Infolist

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Use MapEntry::geojsonData() to render GeoJSON geometry data on an infolist map. This is useful for displaying previously drawn shapes. The geojsonData can be a string or an array.

```php
MapEntry::make('location')
    ->defaultLocation(
        latitude:  fn ($record) => $record?->latitude  ?? 0,
        longitude: fn ($record) => $record?->longitude ?? 0
    )
    ->geojsonData(fn ($record) => $record?->geojson)   // string or array
    ->geoMan(true)
    ->geoManEditable(false)   // view-only; set true to allow editing
    ->zoom(14)
```

--------------------------------

### rangeSelectField()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Links a separate form field to draw a dynamic radius circle around the marker.

```APIDOC
## rangeSelectField(string $targetField)

### Description
Links a separate form field (in meters) to draw a dynamic radius circle around the marker, useful for proximity-based selection.

### Method
`rangeSelectField('search_radius')`

### Parameters
#### Path Parameters
- **targetField** (string) - Required - The name of the sibling form field to watch for radius changes.

### Request Example
```php
use Filament\Forms\Components\Fieldset;
use Filament\
Forms\Components\Select;
use App\Enums\SearchRadius;

Fieldset::make('Search Area')
    ->schema([
        Select::make('search_radius')
            ->enum(SearchRadius::class)
            ->options(SearchRadius::class)   // values must be in meters
            ->required(),

        Map::make('location')
            ->defaultLocation(latitude: 40.4168, longitude: -3.7038)
            ->showMarker(true)
            ->zoom(11)
            ->tilesUrl('https://tile.openstreetmap.de/{z}/{x}/{y}.png')
            ->rangeSelectField('search_radius')  // watches this sibling field
            ->setFilledColor('#bfdbfe'),          // light-blue fill for circle
    ])
    ->columns(1)
```
```

--------------------------------

### boundaries()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Constrains the map pan area to a specified bounding box and auto-centers the default location.

```APIDOC
## boundaries(bool $enabled, ?float $southWestLatitude = null, ?float $southWestLongitude = null, ?float $northEastLatitude = null, ?float $northEastLongitude = null)

### Description
Prevents the map from being panned outside a southwest / northeast bounding box and auto-centers the default location.

### Method
`boundaries(true, 49.5, -11.0, 61.0, 2.0)`

### Parameters
#### Path Parameters
- **enabled** (bool) - Required - Whether to enable boundaries.
- **southWestLatitude** (float) - Optional - The latitude of the southwest corner.
- **southWestLongitude** (float) - Optional - The longitude of the southwest corner.
- **northEastLatitude** (float) - Optional - The latitude of the northeast corner.
- **northEastLongitude** (float) - Optional - The longitude of the northeast corner.

### Request Example
```php
// Restrict to the British Isles
Map::make('location')
    ->boundaries(true, 49.5, -11.0, 61.0, 2.0)  // SW lat, SW lng, NE lat, NE lng
    ->minZoom(6)
    ->showZoomControl(true)
    ->showMarker(true)

// Convenience alias for the same bounding box
Map::make('location')
    ->setBoundsToBritishIsles()
    ->minZoom(6)
```
```

--------------------------------

### Eloquent Model with Virtual Location Attribute

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Integrates map data into an Eloquent model by exposing latitude, longitude, and GeoJSON as a single virtual 'location' attribute. This simplifies direct use with Map::make('location').

```php
<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Casts\Attribute;
use Illuminate\Database\Eloquent\Model;

class Location extends Model
{
    protected $fillable = ['latitude', 'longitude', 'geojson'];

    /**
     * Expose lat/lng as a single 'location' virtual attribute
     * for direct use with Map::make('location').
     */
    protected function location(): Attribute
    {
        return Attribute::make(
            get: fn (mixed $value, array $attributes) => [
                'lat'     => $attributes['latitude']  ?? 0,
                'lng'     => $attributes['longitude'] ?? 0,
                'geojson' => isset($attributes['geojson'])
                                ? json_decode($attributes['geojson'], true)
                                : null,
            ],
            set: fn (array $value) => [
                'latitude'  => $value['lat']     ?? $value['latitude']  ?? 0,
                'longitude' => $value['lng']     ?? $value['longitude'] ?? 0,
                'geojson'   => isset($value['geojson'])
                                ? json_encode($value['geojson'])
                                : null,
            ],
        );
    }
}
```

--------------------------------

### GeoMan Integration

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

Integrates GeoMan for drawing and editing vector geometries on the map.

```APIDOC
## GeoMan Integration — Drawing & Editing Geometries

### Description
Enables the GeoMan toolbar for drawing and editing vector geometries. State is returned as a GeoJSON object under `$state['geojson']`.

### Methods
- `geoMan(bool $enable)`
- `geoManEditable(bool $editable)`
- `geoManPosition(string $position)`
- `drawMarker(bool $enable)`
- `drawPolygon(bool $enable)`
- `drawPolyline(bool $enable)`
- `drawCircle(bool $enable)`
- `drawCircleMarker(bool $enable)`
- `drawRectangle(bool $enable)`
- `drawText(bool $enable)`
- `editPolygon(bool $enable)`
- `cutPolygon(bool $enable)`
- `dragMode(bool $enable)`
- `rotateMode(bool $enable)`
- `deleteLayer(bool $enable)`
- `snappable(bool $enable, ?int $threshold = null)`
- `setColor(string $color)`
- `setFilledColor(string $color)`
- `afterStateUpdated(callable $callback)`

### Request Example
```php
Map::make('location')
    ->geoMan(true)
    ->geoManEditable(true)
    ->geoManPosition('topleft')    // 'topleft' | 'topright' | 'bottomleft' | 'bottomright'
    // Drawing tools
    ->drawMarker(true)
    ->drawPolygon(true)
    ->drawPolyline(true)
    ->drawCircle(true)
    ->drawCircleMarker(true)
    ->drawRectangle(true)
    ->drawText(true)
    // Editing tools
    ->editPolygon(true)
    ->cutPolygon(true)
    ->dragMode(true)
    ->rotateMode(true)
    ->deleteLayer(true)
    // Snapping
    ->snappable(true, 20)          // snap threshold in pixels
    // Colors
    ->setColor('#2563eb')          // stroke color
    ->setFilledColor('#bfdbfe')    // fill color
    ->afterStateUpdated(function (Set $set, ?array $state): void {
        $set('geojson', json_encode($state['geojson'] ?? null));
    })
```
```

--------------------------------

### Configure Range Selection Field

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Use `rangeSelectField` to link map marker radius to a form field. The linked field must specify range in meters.

```php
Fieldset::make('Location')
    ->schema([
        Select::make('membership_distance')
            ->enum(MembershipDistance::class)
            ->options(MembershipDistance::class)
            ->required(),

        Map::make('location')
            ->defaultLocation(latitude: 40.4168, longitude: -3.7038)
            ->showMarker(true)
            ->showFullscreenControl(false)
            ->showZoomControl()
            ->tilesUrl("https://tile.openstreetmap.de/{z}/{x}/{y}.png")
            ->zoom(12)
            ->detectRetina()
            ->rangeSelectField('membership_distance')
            ->setFilledColor('#cad9ec'),
    ])
    ->columns(1),
```

--------------------------------

### Link Radius Selection with rangeSelectField()

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

The `rangeSelectField()` method links a map's radius circle to a separate form field (e.g., a select input for search radius in meters). Changes in the linked field dynamically update the circle's radius on the map. Ensure the linked field's values are in meters.

```php
use Filament\Forms\Components\Fieldset;
use Filament\Forms\Components\Select;
use App\Enums\SearchRadius;

Fieldset::make('Search Area')
    ->schema([
        Select::make('search_radius')
            ->enum(SearchRadius::class)
            ->options(SearchRadius::class)   // values must be in meters
            ->required(),

        Map::make('location')
            ->defaultLocation(latitude: 40.4168, longitude: -3.7038)
            ->showMarker(true)
            ->zoom(11)
            ->tilesUrl('https://tile.openstreetmap.de/{z}/{x}/{y}.png')
            ->rangeSelectField('search_radius')  // watches this sibling field
            ->setFilledColor('#bfdbfe'),          // light-blue fill for circle
    ])
    ->columns(1)
```

--------------------------------

### Map::make() - Form Field

Source: https://context7.com/dotswan/filament-map-picker/llms.txt

The `Map` component extends Filament's `Field` and provides an interactive map within forms. It updates its state with latitude, longitude, and optional GeoJSON data upon marker movement or map clicks.

```APIDOC
## Map::make() - Form Field

### Description
The `Map` component extends `Filament\Forms\Components\Field` and renders an interactive map inside a Filament resource form. On marker move or map click, the field state is updated with `['lat' => float, 'lng' => float, 'geojson' => array|null]`.

### Method
`Map::make(string $name)`

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```php
use Dotswan\MapPicker\Fields\Map;

Map::make('location')
    ->label('Pick a Location')
    ->columnSpanFull()
    ->defaultLocation(latitude: 40.4168, longitude: -3.7038)  // Madrid
    ->draggable(true)
    ->clickable(true)           // click map to move marker
    ->zoom(13)
    ->minZoom(5)
    ->maxZoom(18)
    ->tilesUrl('https://tile.openstreetmap.de/{z}/{x}/{y}.png')
    ->detectRetina(true)
    ->showMarker(true)
    ->markerColor('#e11d48')
    ->showZoomControl(true)
    ->showFullscreenControl(true)
    ->extraStyles(['min-height: 60vh', 'border-radius: 12px'])
    ->afterStateUpdated(function (Set $set, ?array $state): void {
        // Sync lat/lng hidden fields whenever the marker moves
        $set('latitude',  $state['lat']  ?? null);
        $set('longitude', $state['lng']  ?? null);
    })
    ->afterStateHydrated(function ($state, $record, Set $set): void {
        // Restore marker position when editing an existing record
        if ($record) {
            $set('location', [
                'lat' => $record->latitude,
                'lng' => $record->longitude,
            ]);
        }
    });
```

### Response
#### Success Response (200)
- **state** (array) - Contains 'lat', 'lng', and optional 'geojson' keys.
```

--------------------------------

### Set Boundaries to British Isles

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

A convenience function to set map boundaries specifically to the British Isles region.

```php
Map::make('location')
    ->setBoundsToBritishIsles()
    ->showMarker()
    ->draggable()
```

--------------------------------

### Add Hidden Form Fields for Latitude and Longitude

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Includes hidden input fields for latitude and longitude in a Filament form. These fields store the coordinates without being visible to the user, often used in conjunction with map pickers.

```php
TextInput::make('latitude')
    ->hiddenLabel()
    ->hidden(),

TextInput::make('longitude')
    ->hiddenLabel()
    ->hidden()
```

--------------------------------

### Custom Location Attribute in Eloquent Model

Source: https://github.com/dotswan/filament-map-picker/blob/master/README.md

Define a custom attribute to handle latitude and longitude as a single location field. This approach consolidates location data within your model, simplifying data management.

```php
class YourModel extends Model
{
    protected function location(): Attribute
    {
        return Attribute::make(
            get: fn (mixed $value, array $attributes) => [
                'latitude' => $attributes['latitude'],
                'longitude' => $attributes['longitude']
            ],
            set: fn (array $value) => [
                'latitude' => $value['latitude'],
                'longitude' => $value['longitude']
            ],
        );
    }
}
```
Tokens:
Raw