Pinpoint

• Features
• Requirements
• Installation
• Configuration
  • 1. Choose a map provider
  • 2. Google Maps — set your API Key
  • 3. Leaflet — optional configuration
  • 4. Publish the config file (optional)
• Usage
  • Basic Usage (Google Maps)
  • Using Leaflet (Free / No API Key)
  • Full Example with All Options
  • Radius Support
  • Disable Features
  • Using with Repeater
  • Infolist Entry (Read-Only Display)
    • Single Marker
    • Multiple Markers (New in v1.1.3)
    • Pin Customization Options
    • Custom Marker Icons
    • Customization Options
• Available Methods
  • Pinpoint (Form Field)
  • PinpointEntry (Infolist Entry)
• Getting a Google Maps API Key (Google provider only)
• Database Migration
• Translations
  • Publishing Translations
  • Adding New Languages
• Changelog
• Contributing
• Security
• Credits
• License

📍 A location picker component for Filament 4 & 5 supporting Google Maps and Leaflet.js (OpenStreetMap) — with search, draggable marker, and reverse geocoding support.

#Features

• 🗺️ Two map providers — Google Maps (default) or Leaflet.js / OpenStreetMap (free, no API key)
• 🔍 Search location — Google Places Autocomplete (Google) or Nominatim (Leaflet)
• 📍 Click to set marker — Click anywhere on the map to place a marker
• ✋ Draggable marker — Drag the marker to fine-tune the location
• 📱 Current location — Get user's current device location
• ⭕ Radius support — Display and edit radius around the location
• 🏠 Reverse geocoding — Auto-fill address fields from coordinates
• 🌙 Dark mode support — Fully compatible with Filament's dark mode
• 🌐 Multi-language support — Translations for EN, AR, NL, ID
• ⚙️ Fully configurable — Customize height, zoom, default location, and more

#Requirements

• PHP 8.1+
• Laravel 10+ / 11+ / 12+
• Filament 4.0+ / 5.0+
• Google Maps provider (default): API Key with Maps JavaScript API, Places API, and Geocoding API enabled
• Leaflet provider: No API key required

#Installation

Install the package via Composer:

composer require fahiem/filament-pinpoint

#Configuration

#1. Choose a map provider

The default provider is Google Maps. To use Leaflet.js (OpenStreetMap) instead, set in your .env:

PINPOINT_PROVIDER=leaflet

You can also override the provider per field instance:

Pinpoint::make('location')->provider('leaflet')

#2. Google Maps — set your API Key

Required only when using provider = google:

GOOGLE_MAPS_API_KEY=your_api_key_here

#3. Leaflet — optional configuration

Leaflet works out of the box with OpenStreetMap tiles. Optionally customize:

# Custom tile server (default: OpenStreetMap)
LEAFLET_TILE_URL=https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png

# Optional dark mode tile URL (e.g. CartoDB Dark)
LEAFLET_TILE_URL_DARK=https://{s}.basemaps.cartocdn.com/dark_all/{z}/{x}/{y}{r}.png

# Nominatim base URL for search & reverse geocoding (default: nominatim.openstreetmap.org)
NOMINATIM_URL=https://nominatim.openstreetmap.org

#4. Publish the config file (optional)

php artisan vendor:publish --tag="filament-pinpoint-config"

You can also set default map values via environment variables:

GOOGLE_MAPS_DEFAULT_LAT=-6.200000
GOOGLE_MAPS_DEFAULT_LNG=106.816666
GOOGLE_MAPS_DEFAULT_ZOOM=15
GOOGLE_MAPS_DEFAULT_HEIGHT=500

#Usage

#Basic Usage (Google Maps)

use Fahiem\FilamentPinpoint\Pinpoint;

public static function form(Form $form): Form
{
    return $form
        ->schema([
            Pinpoint::make('location')
                ->label('Location')
                ->latField('lat')
                ->lngField('lng'),

            TextInput::make('lat')
                ->label('Latitude')
                ->readOnly(),

            TextInput::make('lng')
                ->label('Longitude')
                ->readOnly(),
        ]);
}

#Using Leaflet (Free / No API Key)

Set the provider globally via .env:

PINPOINT_PROVIDER=leaflet

Or per field instance:

Pinpoint::make('location')
    ->provider('leaflet')
    ->latField('lat')
    ->lngField('lng')
    ->addressField('address')
    ->draggable()
    ->searchable()

Same API, same methods — Leaflet uses OpenStreetMap tiles and Nominatim for search and reverse geocoding. No API key needed.

For PinpointEntry (infolist):

PinpointEntry::make('location')
    ->provider('leaflet')
    ->latField('lat')
    ->lngField('lng')
    ->columnSpanFull()

#Full Example with All Options

use Fahiem\FilamentPinpoint\Pinpoint;

Pinpoint::make('location')
    ->label('Business Location')
    ->defaultLocation(-6.200000, 106.816666) // Jakarta
    ->defaultZoom(15)
    ->height(400)
    ->draggable()
    ->searchable()
    ->latField('lat')
    ->lngField('lng')
    ->addressField('address')            // Auto-fill address field
    ->shortAddressField('short_address') // Auto-fill short address field (exclude province, city, district, village, and postal code)
    ->provinceField('province')          // Auto-fill province field
    ->cityField('city')                  // Auto-fill city/county field
    ->districtField('district')          // Auto-fill district field
    ->villageField('village')            // Auto-fill village/district field
    ->postalCodeField('postal_code')     // Auto-fill postal/zip code field
    ->countryField('country')            // Auto-fill country field
    ->streetField('street')              // Auto-fill street field
    ->streetNumberField('street_number') // Auto-fill street number field
    ->columnSpanFull()

#Radius Support

You can enable radius support by using radiusField():

Pinpoint::make('location')
    ->radiusField('radius') // 'radius' is the column name in your database
    ->defaultRadius(500)    // Default 500 meters

When radiusField is configured, an interactive blue circle will appear on the map. You can:

• Resize the radius by dragging the small white handle on the circle's edge
• View the radius visually on the map
• The radius value (in meters) is automatically saved to your database field in real-time
• The circle uses proper z-index layering so the marker always appears on top

Visual hierarchy:

• Marker (pin): zIndex 200 - always on top
• Circle (radius): zIndex 100 - below the marker

#Disable Features

Pinpoint::make('location')
    ->draggable(false)  // Disable marker dragging
    ->searchable(false) // Hide search box

#Using with Repeater

Pinpoint fully supports Filament's Repeater component. Each repeater item gets its own independent map and fields:

use Fahiem\FilamentPinpoint\Pinpoint;
use Filament\Forms\Components\Repeater;
use Filament\Forms\Components\TextInput;

Repeater::make('branches')
    ->schema([
        TextInput::make('branch_name')
            ->label('Branch Name')
            ->required(),

        Pinpoint::make('location')
            ->label('Location')
            ->latField('latitude')
            ->lngField('longitude')
            ->addressField('address')
            ->draggable()
            ->searchable()
            ->height(300),

        TextInput::make('latitude')
            ->label('Latitude')
            ->readOnly(),

        TextInput::make('longitude')
            ->label('Longitude')
            ->readOnly(),

        TextInput::make('address')
            ->label('Address')
            ->readOnly()
            ->columnSpanFull(),
    ])
    ->columns(2)
    ->columnSpanFull()

Note: When using with Repeater, the field paths are automatically calculated (e.g., data.branches.0.latitude for the first item).

#Infolist Entry (Read-Only Display)

For displaying locations in infolists (view mode), use the PinpointEntry component. It displays a clean, read-only map with a marker at the specified coordinates.

#Single Marker

use Fahiem\FilamentPinpoint\PinpointEntry;

public static function infolist(Infolist $infolist): Infolist
{
    return $infolist
        ->schema([
            PinpointEntry::make('location')
                ->label('Location')
                ->latField('lat')
                ->lngField('lng')
                ->columnSpanFull(),
        ]);
}

#Multiple Markers (New in v1.1.3)

Display multiple locations on a single map:

PinpointEntry::make('branches')
    ->label('Branch Locations')
    ->pins([
        [
            'lat' => -6.200000,
            'lng' => 106.816666,
            'label' => 'Jakarta Office',
            'color' => 'red',
        ],
        [
            'lat' => -6.914744,
            'lng' => 107.609810,
            'label' => 'Bandung Office',
            'color' => 'blue',
        ],
        [
            'lat' => -7.797068,
            'lng' => 110.370529,
            'label' => 'Yogyakarta Office',
            'color' => 'green',
        ],
    ])
    ->fitBounds() // Auto-zoom to show all markers
    ->height(500)
    ->columnSpanFull()

#Pin Customization Options

Each pin in the pins() array supports:

#Custom Marker Icons

PinpointEntry::make('locations')
    ->pins([
        [
            'lat' => -6.200000,
            'lng' => 106.816666,
            'label' => 'Main Office',
            'icon' => 'https://example.com/custom-marker.png', // Custom icon URL
        ],
        [
            'lat' => -6.914744,
            'lng' => 107.609810,
            'label' => 'Warehouse',
            'info' => '<div style="padding: 10px;"><strong>Warehouse A</strong><br>Open 24/7</div>', // Custom HTML
        ],
    ])
    ->columnSpanFull()

#Customization Options

PinpointEntry::make('location')
    ->label('Business Location')
    ->defaultLocation(-6.200000, 106.816666) // Jakarta
    ->defaultZoom(15)
    ->height(400)
    ->latField('lat')
    ->lngField('lng')
    ->fitBounds(false) // Disable auto-fit bounds
    ->columnSpanFull()

The PinpointEntry displays:

• A read-only map (Google Maps or Leaflet) with single or multiple markers
• Optional info windows / popups with labels or custom HTML content
• Auto-fit bounds to display all markers
• Full dark mode support

#Available Methods

#Pinpoint (Form Field)

#PinpointEntry (Infolist Entry)

#Getting a Google Maps API Key (Google provider only)

1. Go to Google Cloud Console
2. Create a new project or select an existing one
3. Enable the following APIs:
   • Maps JavaScript API
   • Places API
   • Geocoding API
4. Go to Credentials and create an API key
5. (Recommended) Restrict your API key to specific domains

#Database Migration

Make sure your table has columns for latitude and longitude:

Schema::create('locations', function (Blueprint $table) {
    $table->id();
    $table->string('name');
    $table->decimal('lat', 10, 7)->nullable();
    $table->decimal('lng', 10, 7)->nullable();
    $table->text('address')->nullable();
    $table->text('short_address')->nullable();
    $table->string('province')->nullable();
    $table->string('city')->nullable();
    $table->string('district')->nullable();
    $table->string('village')->nullable();
    $table->string('postal_code')->nullable();
    $table->string('country')->nullable();
    $table->string('street')->nullable();
    $table->string('street_number')->nullable();
    $table->timestamps();
});

#Translations

This package supports multiple languages out of the box:

#Publishing Translations

To customize the translations, publish them to your application:

php artisan vendor:publish --tag="filament-pinpoint-translations"

This will publish the translation files to lang/vendor/filament-pinpoint/.

#Adding New Languages

Create a new folder in lang/vendor/filament-pinpoint/{locale}/ with a pinpoint.php file:

<?php

return [
    'search' => 'Your translation...',
    'use_my_location' => 'Your translation...',
    'instructions' => 'Your translation...',
    'loading_map' => 'Your translation...',
];

#Changelog

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

#Contributing

Please see CONTRIBUTING for details.

#Security

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

#Credits

• Fahiem
• All Contributors

#License

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