Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/diegobas/filament-drawable-map/llms.txt

Use this file to discover all available pages before exploring further.

The ViewableMap field renders a non-editable Google Maps canvas that displays one or more pre-existing polygon zones. It is designed for detail pages, infolist panels, or any form context where users need to inspect geographic areas without being able to modify them. Polygons support individual colours, hover tooltips, and click-to-zoom behaviour out of the box.

​
Basic Usage

Display a single polygon stored in a model attribute: 
use DiegoBas\FilamentDrawableMap\Forms\Components\ViewableMap;

ViewableMap::make('zone')
    ->label('Delivery Zone')
    ->color('#4285F4'),
The field reads its value directly from the model attribute named zone. The value must be a JSON string or a PHP array of lat/lng coordinate objects — the same format produced by DrawableMap.

​
Displaying Multiple Polygons

Use polygons() to supply an explicit array of polygon coordinate sets and titles() to attach a hover tooltip to each one. 
ViewableMap::make('zones_display')
    ->label('All Zones')
    ->polygons(fn ($record) => [
        json_decode($record->zone_a, true),
        json_decode($record->zone_b, true),
    ])
    ->titles(['Zone A', 'Zone B'])
    ->color('#4285F4'),
The map auto-fits its viewport to show all supplied polygons on first render. Each polygon is drawn using the colour resolved from color(). The initial map centre is taken from the package’s published config (filament-drawable-map.location.latitude / filament-drawable-map.location.longitude) — ViewableMap does not expose a location() setter.

​
Method Reference

​
make
string
required
The field name. In single-polygon mode this must match the model attribute that holds the coordinate JSON. In multi-polygon mode (when polygons() is provided) the name is still required by Filament’s field system but the field’s own state value is ignored.
​
polygons
array | Closure | null
An explicit array of polygon coordinate sets to display. Each element is itself an array of coordinate objects in the form [['lat' => ..., 'lng' => ...], ...]. Accepts a Closure that receives the current $record.When polygons() is not called, the component falls back to reading its own Livewire-entangled state value (the single model attribute).
->polygons(fn ($record) => [
    json_decode($record->zone_a, true),
    json_decode($record->zone_b, true),
])
​
titles
array | Closure | null
An array of tooltip strings, one per polygon, shown as a floating popup bubble when the user hovers over that polygon. The order must match the order of entries in polygons().
->titles(['Northern Zone', 'Southern Zone'])
​
color
string | Closure | null
A hex colour string applied to the polygon stroke and semi-transparent fill. In multi-polygon mode this serves as the fallback colour for any polygon whose index has no entry in the resolved colours array.Default: '#FF0000'.
->color('#34A853')
​
mode
string
Overrides the map colour scheme. Accepted values are 'light' and 'dark'. When not set, the component checks localStorage.theme and the browser’s prefers-color-scheme media query, so it tracks the active Filament theme automatically without any configuration.
->mode('dark')
​
disabled
bool | Closure
When true, gesture handling is set to 'none' and map icon clicks are disabled at the Google Maps SDK level. The polygons remain visible but the map cannot be panned or zoomed by the user.
getTitles(), getColor(), getMode(), getPolygons(), getState(), and callAfterStateHydrated() are internal lifecycle and accessor methods used by the Filament framework and the Blade template. You do not call these directly in your form schema.

​
Interaction

ViewableMap is read-only but still provides several passive interactions to help users navigate between zones.

Hover tooltip

Move the pointer over any polygon to show a floating bubble containing its title. The bubble disappears when the pointer leaves the polygon.

Click to zoom

Click a polygon to fit and pan the map to that polygon’s bounding box.

Auto-fit on load

On initialisation the map automatically calculates a global bounding box across all polygons and fits the viewport to show all of them at once.

Dark mode sync

The component listens for the dark-mode-toggled window event dispatched by Filament and switches between the light and dark Google Maps colour scheme without a page reload.

​
State Format

In single-polygon mode the field reads its value from the model attribute. The stored value must be a JSON string or PHP array of coordinate objects: 
[
  {"lat": 40.4168, "lng": -3.7038},
  {"lat": 40.4200, "lng": -3.7000}
]
The component handles JSON decoding automatically during state hydration, so a json database column is all that is needed: 
$table->json('zone')->nullable();
And in your model: 
protected $casts = [
    'zone' => 'array',
];
When polygons() is provided, the field’s own state value (the model attribute bound to make()) is completely ignored. All coordinate data is taken exclusively from the array returned by your polygons() closure. You can therefore pass any field name to make() — it only serves as a unique identifier within the Filament form schema.
The map canvas is fixed at 400 px tall by the component’s built-in inline style. This height cannot be changed through the PHP API — override it in your application’s stylesheet if a different height is required.

Build docs developers (and LLMs) love

Get started for freeTalk to us