Arcs

Docs / Arcs

Overview

The <x-map-arc> component draws curved connections between pairs of points: flight paths, shipping lanes, trade flows, or any origin → destination data. Each arc is a quadratic Bézier curve that crosses the antimeridian the short way, so a Tokyo → San Francisco arc goes over the Pacific instead of around the world.

Pass an array of arcs to the :data prop. Each item needs from and to as [lng, lat] pairs and an optional id. Any extra fields become feature properties you can use in paint expressions, tooltips and popups.

Basic Usage

Connect one hub to several destinations:

// In your Livewire component
public array $flights = [
    ['id' => 'lhr-jfk', 'from' => [-0.1276, 51.5072], 'to' => [-74.006, 40.7128]],
    ['id' => 'lhr-dxb', 'from' => [-0.1276, 51.5072], 'to' => [55.2708, 25.2048]],
    ['id' => 'lhr-sin', 'from' => [-0.1276, 51.5072], 'to' => [103.8198, 1.3521]],
    // ...
];

<!-- In your Blade view -->
<x-map :center="[10, 25]" :zoom="1.2" height="320px">
    <x-map-arc :data="$flights" />
</x-map>

Curvature

:curvature controls how far each arc bows away from the straight line (default 0.2). Use 0 for straight lines and a negative value to bow the other way. :samples sets how many points make up each curve (default 64).

blade

<x-map-arc
    :data="$flights"
    :curvature="0.35"
    :samples="96"
    :paint="['line-color' => '#f97316', 'line-width' => 3]"
    :fit-bounds="true"
/>

Interactive Arcs

Style arcs from their data with MapLibre expressions, highlight the hovered arc with :hover-paint, and show a tooltip with the <x-slot:tooltip> slot. This example colors air and sea routes with a match expression on a globe. Hover or click an arc:

// In your Livewire component
public array $shipments = [
    [
        'id' => 'sha-rtm',
        'from' => [121.4737, 31.2304],
        'to' => [4.4777, 51.9244],
        'origin' => 'Shanghai',
        'destination' => 'Rotterdam',
        'mode' => 'sea',
        'days' => 32,
    ],
    [
        'id' => 'nrt-sfo',
        'from' => [139.6917, 35.6895],
        'to' => [-122.4194, 37.7749],
        'origin' => 'Tokyo',
        'destination' => 'San Francisco',
        'mode' => 'air',
        'days' => 1,
    ],
    // ...
];

<!-- In your Blade view -->
<x-map projection="globe" :center="[50, 25]" :zoom="1.4" height="320px">
    <x-map-arc
        :data="$shipments"
        :paint="[
            'line-color' => ['match', ['get', 'mode'], 'air', '#a78bfa', 'sea', '#34d399', '#888888'],
            'line-width' => 2,
        ]"
        :hover-paint="['line-width' => 4, 'line-opacity' => 1]"
    >
        <x-slot:tooltip>
            <strong>{origin}</strong> → <strong>{destination}</strong> · {mode}
        </x-slot:tooltip>
        <x-slot:popup>
            <div>{origin} → {destination}</div>
            <div>By {mode} · about {days} day(s)</div>
        </x-slot:popup>
    </x-map-arc>
</x-map>

In the tooltip and popup slots, {property} placeholders are replaced with the hovered arc's properties (values are HTML-escaped). {lat} and {lng} resolve to the pointer position. A wider invisible hit layer sits under each arc, so even thin arcs are easy to hover.

Paint & layout

:paint is merged over the defaults (line-color: #4285F4, line-width: 2, line-opacity: 0.85) and accepts any MapLibre line paint property, including data-driven expressions. :layout takes line layout properties (defaults to round joins and caps). :hover-paint values are applied only to the arc under the pointer.

Livewire Events

Interactive arcs dispatch map:arc-clicked and map:arc-hovered. The payload contains the arc layer id, the original arc item from your data, the pointer lat/lng and the mapId. When the pointer leaves an arc, map:arc-hovered fires again with arc: null. Click an arc below:

No arc selected yet.

// In your Livewire component
use Livewire\Attributes\On;

public ?array $selectedArc = null;

#[On('map:arc-clicked')]
public function selectArc(string $id, ?array $arc = null): void
{
    if ($id === 'events-arcs') {
        $this->selectedArc = $arc;
    }
}

<!-- In your Blade view -->
<x-map id="arcs-events-map" :center="[10, 25]" :zoom="1.2">
    <x-map-arc
        id="events-arcs"
        :data="$flights"
        :hover-paint="['line-color' => '#0891b2', 'line-width' => 5]"
    />
</x-map>

<!-- Or listen in Alpine -->
<div x-on:map:arc-hovered="console.log($event.detail.arc)">...</div>

Updating arc data

Arcs react to Livewire state: change the array bound to :data and the layer updates in place on the next render. To push new data without re-rendering, dispatch map:update-arc-data-{id}:

php

$this->dispatch('map:update-arc-data-events-arcs', data: $this->flights);

Props

Prop	Type	Default	Description
:data	array	[]	Arcs as ['id' => ..., 'from' => [lng, lat], 'to' => [lng, lat], ...]. Extra fields become feature properties
id	?string	uuid	Layer id, used in event payloads and map:update-arc-data-{id}
:curvature	float	0.2	How far arcs bow. 0 = straight, negative bows the other way
:samples	int	64	Points per curve
:paint	array	[]	MapLibre line paint, merged over the defaults. Supports expressions
:layout	array	[]	MapLibre line layout
:hover-paint	?array	null	Paint applied to the hovered arc
:interactive	bool	true	Enable hover, tooltip, popup and click events
before-id	?string	null	Insert the layer below this existing layer id
:fit-bounds	bool	false	Fit the map to all arcs once loaded

Slots

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

Previous ← Clusters Next GeoJSON →