> ## Documentation Index
> Fetch the complete documentation index at: https://flex-fields.bjanczak.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Examples target Filament 5. Verify optional dependencies before configuring integrations.
> Upload transfer completion, permanent storage and record acceptance are separate milestones. Native and Spatie image conversions retain the original.

# MapCoordinatesField

> Choose latitude and longitude on a map, through coordinate inputs or with optional browser geolocation.

<video autoPlay muted loop playsInline controls preload="metadata" src="https://mintcdn.com/flex-fields/cY70dYD2SDr8chb8/art/previews/map-coordinates-motion.mp4?fit=max&auto=format&n=cY70dYD2SDr8chb8&q=85&s=22274c8a79421e5ce70a5fbd8ce0fa4a" poster="/art/previews/map-coordinates.webp" width="1920" height="1080" aria-label="MapCoordinatesField — FLEX Fields demonstration">
  [Watch the MapCoordinatesField demonstration (MP4).](https://flex-fields.bjanczak.com/art/previews/map-coordinates-motion.mp4)
</video>

`MapCoordinatesField` selects a single geographic point without address search or reverse geocoding. Use it for equipment positions, meeting points and coordinates that do not need a street address.

## Basic usage

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
use Bjanczak\FilamentFlexFields\Filament\Forms\Components\MapCoordinatesField;

MapCoordinatesField::make('coordinates')
    ->label('Meeting point')
    ->mapProvider('maplibre')
    ->defaultCenter([52.2297, 21.0122])
    ->defaultZoom(12)
    ->mapHeight(420)
    ->geolocation()
    ->fullscreen()
    ->required();
```

The component enables manual coordinate inputs and stores `lat` and `lng`. Address search and reverse geocoding are disabled by default. MapLibre's default rendering setup needs no Mapbox token; a custom tile/style provider may have its own requirements.

## State and database storage

Use a JSON column with an Eloquent `array` cast:

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
protected function casts(): array
{
    return ['coordinates' => 'array'];
}
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"lat": 52.2297, "lng": 21.0122}
```

`defaultCenter()` sets the initial camera; it does not select or save a point. Use `default(['lat' => 52.2297, 'lng' => 21.0122])` for an initial field value. Existing model values hydrate through the normal Filament form flow.

## Input and selection policies

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
MapCoordinatesField::make('coordinates')
    ->mapProvider('maplibre')
    ->manualCoordinates()
    ->selectOnMapClick()
    ->draggableMarkers()
    ->allowedBounds([14, 49, 24.2, 55])
    ->clearable()
    ->scale()
    ->scaleUnit('nautical');
```

Use `manualCoordinates(false)` to hide the numeric inputs, `selectOnMapClick(false)` to disable point placement by clicking, and `draggableMarkers(false)` to disable dragging. `readOnly()` blocks value changes while retaining map viewing controls.

Latitude and longitude are validated on the server, together with configured bounds/radius policies. The coordinate inputs are not the validation boundary. `requiredFields(['lat', 'lng'])` is configured by the component; `required()` additionally makes an empty selection invalid.

## Optional device location

`geolocation()` adds a location action. It requests browser permission only after the user activates it, requires a secure browser context and can fail if permission or a device location is unavailable. It does not continuously track the device.

See [shared map configuration](https://flex-fields.bjanczak.com/docs/location-v4.md) for providers, GPS timeouts, camera controls, appearance and coordinate order. `defaultCenter()` takes `[latitude, longitude]`; GeoJSON and radius centers take `[longitude, latitude]`.

## Related components

* [MapPickerField](https://flex-fields.bjanczak.com/docs/mappickerfield.md) — select a point with a structured address.
* [MapMarkersField](https://flex-fields.bjanczak.com/docs/map-markers.md) — collect several points.
* [MapDisplayField](https://flex-fields.bjanczak.com/docs/map-display.md) — present supplied map layers.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.