GeoJSON

Docs / GeoJSON

Overview

The <x-map-geojson> component renders any GeoJSON as map layers: polygons become fills with outlines, lines become strokes and points become circles. Use it for delivery zones, boundaries, choropleths, trails or any shapes you already have as GeoJSON.

:data accepts a FeatureCollection, a single Feature or a bare geometry as a PHP array, or a URL string that MapLibre fetches in the browser. Default colors are neutral and follow the map's light/dark theme.

Basic Usage

The smallest example: a single polygon with the default theme-aware styling.

blade

<x-map height="320px">
    <x-map-geojson
        :data="[
            'type' => 'Polygon',
            'coordinates' => [[[-0.15, 51.52], [-0.12, 51.52], [-0.12, 51.50], [-0.15, 51.50], [-0.15, 51.52]]],
        ]"
        :fit-bounds="true"
    />
</x-map>

Overlay on a Map

Style features from their properties with expressions such as ['get', 'color'], highlight the hovered feature with the *-hover-paint props, and describe it in a tooltip slot. Set :interactive="true" to enable hover, tooltips, popups and click events (GeoJSON layers are not interactive by default). Hover the delivery zones and depots:

// In your Livewire component
public array $zones = [
    'type' => 'FeatureCollection',
    'features' => [
        [
            'type' => 'Feature',
            'properties' => ['name' => 'West End', 'detail' => '128 orders today', 'color' => '#8b5cf6'],
            'geometry' => ['type' => 'Polygon', 'coordinates' => [[
                [-0.152, 51.516], [-0.133, 51.520], [-0.123, 51.512],
                [-0.130, 51.504], [-0.148, 51.506], [-0.152, 51.516],
            ]]],
        ],
        [
            'type' => 'Feature',
            'properties' => ['name' => 'Soho depot', 'detail' => 'Open 24/7'],
            'geometry' => ['type' => 'Point', 'coordinates' => [-0.134, 51.513]],
        ],
        // ...
    ],
];

<!-- In your Blade view -->
<x-map height="320px">
    <x-map-geojson
        id="delivery-zones"
        :data="$zones"
        :fill-paint="['fill-color' => ['get', 'color'], 'fill-opacity' => 0.3]"
        :fill-hover-paint="['fill-opacity' => 0.55]"
        :line-paint="['line-color' => ['get', 'color'], 'line-width' => 2]"
        :circle-paint="['circle-color' => '#0f172a', 'circle-radius' => 6]"
        :circle-hover-paint="['circle-radius' => 8]"
        :interactive="true"
        :fit-bounds="true"
    >
        <x-slot:tooltip><strong>{name}</strong><br>{detail}</x-slot:tooltip>
    </x-map-geojson>
</x-map>

How layers are built

Each geometry type gets its own layer, and every paint prop is merged over theme-aware defaults:

Paint prop	Applies to	Defaults
:fill-paint	Polygon, MultiPolygon	fill-color light grey (dark grey in dark mode)
:line-paint	LineString, MultiLineString and polygon outlines	line-color white (near-black in dark mode), line-width 0.5
:circle-paint	Point, MultiPoint	circle-color grey, circle-radius 5, white 1.5px stroke

Pass false to a paint prop to drop that layer entirely, e.g. :line-paint="false" for fills without outlines. Hover works without promote-id because feature ids are generated automatically; set promote-id when you need a stable id from a property.

Blank Map

Add blank to <x-map> for a transparent style with no basemap, so your GeoJSON is the whole map. This example loads Natural Earth country outlines from a URL and colors them by continent:

<x-map :blank="true" :center="[15, 25]" :zoom="0.6" :render-world-copies="false">
    <x-map-geojson
        data="https://cdn.jsdelivr.net/gh/nvkelso/natural-earth-vector@v5.1.2/geojson/ne_110m_admin_0_countries.geojson"
        :fill-paint="[
            'fill-color' => ['match', ['get', 'CONTINENT'],
                'Africa', '#f59e0b',
                'Asia', '#ef4444',
                'Europe', '#3b82f6',
                'North America', '#10b981',
                'South America', '#8b5cf6',
                'Oceania', '#06b6d4',
                '#94a3b8',
            ],
            'fill-opacity' => 0.75,
        ]"
        :fill-hover-paint="['fill-opacity' => 1]"
        :line-paint="['line-color' => '#ffffff', 'line-width' => 0.6]"
        :interactive="true"
    >
        <x-slot:tooltip><strong>{NAME}</strong><br>{CONTINENT}</x-slot:tooltip>
    </x-map-geojson>
</x-map>

When data is a URL, the file is fetched by the browser, so the server must allow cross-origin requests. :fit-bounds only works with inline array data; set :center and :zoom (or the map's :bounds) for URL data.

Livewire Events

Interactive GeoJSON layers dispatch map:geojson-clicked and map:geojson-hovered with the layer id, the feature (id, properties, geometry), the pointer lat/lng and the mapId. When the pointer leaves a feature, map:geojson-hovered fires with feature: null.

php

use Livewire\Attributes\On;

public ?string $selectedZone = null;

#[On('map:geojson-clicked')]
public function selectZone(string $id, ?array $feature = null): void
{
    if ($id === 'delivery-zones') {
        $this->selectedZone = $feature['properties']['name'] ?? null;
    }
}

// Replace the data without re-rendering the component
$this->dispatch('map:update-geojson-delivery-zones', data: $this->zones);

Like every map layer, <x-map-geojson> also reacts to Livewire state: change the bound :data or paint props and the layer updates in place on the next render.

Props

Prop	Type	Default	Description
:data	array\|string	[]	FeatureCollection, Feature or Geometry array, or a URL to a GeoJSON file
id	?string	uuid	Layer id, used in event payloads and map:update-geojson-{id}
promote-id	?string	null	Feature property to use as the feature id (ids are generated when omitted)
:fill-paint	array\|false\|null	null	Fill paint for polygons, merged over defaults. false drops the layer
:line-paint	array\|false\|null	null	Line paint for lines and polygon outlines. false drops the layer
:circle-paint	array\|false\|null	null	Circle paint for points. false drops the layer
:fill-hover-paint	?array	null	Fill paint applied to the hovered feature
:line-hover-paint	?array	null	Line paint applied to the hovered feature
:circle-hover-paint	?array	null	Circle paint applied to the hovered feature
:interactive	bool	false	Enable hover, tooltip, popup and click events
before-id	?string	null	Insert the layers below this existing layer id
:fit-bounds	bool	false	Fit the map to the data once loaded (inline data only)
:fit-bounds-padding	int	40	Padding in pixels for :fit-bounds

Slots

Slot	Description
tooltip	HTML shown on hover. {property}, {lat} and {lng} placeholders are filled in (values are HTML-escaped)
popup	HTML shown in a popup on click, with the same placeholders

Previous ← Arcs Next Advanced →