Map

Overview

The <x-map> component is the foundational building block for all maps. It initializes MapLibre GL JS, sets up the viewport, and provides the container for all child components like markers, popups, routes, clusters, arcs and GeoJSON layers. Children react to Livewire state: when your component re-renders, they update in place while the map itself is preserved (the map uses wire:ignore.self, so you never need to wrap it in wire:ignore). Until the style has loaded, a loading overlay is shown; you can customise or disable it.

Basic Usage

<x-map
    :center="[-0.09, 51.505]"
    :zoom="13"
    height="320px"
    provider="carto-voyager"
/>

Tile Providers

Switch between built-in tile providers using the provider prop. You can also supply a custom MapLibre style (a URL or a style array) via the style prop.

Carto Positron (Light)

<x-map
    :center="[-74.006, 40.7128]"
    :zoom="11"
    height="320px"
    provider="carto-positron"
/>

Carto Dark Matter

<x-map
    :center="[2.3522, 48.8566]"
    :zoom="12"
    height="320px"
    provider="carto-dark-matter"
/>

OpenFreeMap Liberty

<x-map
    :center="[-0.1246, 51.5007]"
    :zoom="15"
    :pitch="50"
    provider="openfreemap-liberty"
    theme="light"
/>

Theme Support

The theme prop controls how the map responds to dark mode. With "auto" (default) the map follows a dark / light class or a data-theme attribute on <html>, swapping styles live and dispatching map:theme-changed. Set follow_system_theme to true in the config to also follow the OS preference when neither is present. Force a theme with "light" / "dark", or switch at runtime with the map:set-theme command.

• Light mode uses provider (or light-style); dark mode uses dark-style, falling back to the configured dark_provider.
• A style (or light-style) applies to both themes unless you also set dark-style.
• Anywhere a style is accepted you can pass a provider key, e.g. dark-style="openfreemap-positron".

<x-map
    :center="[139.6917, 35.6895]"
    :zoom="10"
    height="320px"
    theme="auto"
/>

<!-- This map will switch to dark tiles when .dark is on <html> -->

Globe Projection

Set projection="globe" to render the world as a sphere at low zoom. MapLibre transitions to a flat map as you zoom in. It pairs well with arcs.

<x-map projection="globe" :center="[20, 20]" :zoom="1.4" />

Bounds & Camera

Use :bounds to fit an area when the map loads (instead of :center/:zoom), and :max-bounds to stop users panning away. Bounds are [[west, south], [east, north]]. :zoom accepts floats and 0.

<x-map
    :bounds="[[-0.25, 51.45], [0.05, 51.56]]"
    :bounds-padding="20"
    :max-bounds="[[-0.6, 51.3], [0.4, 51.7]]"
    :min-zoom="9"
/>

Gesture props such as :drag-rotate, :touch-zoom-rotate, :pitch-with-rotate and :cooperative-gestures (Ctrl/⌘ + scroll to zoom, two fingers to pan on touch) are useful for maps embedded in long pages.

Blank Map

Add :blank="true" for a transparent style with no basemap. Combine it with <x-map-geojson> to build choropleths and diagrams where your data is the whole map.

<x-map :blank="true" :center="[15, 25]" :zoom="0.6">
    <x-map-geojson data="https://example.com/countries.geojson" :interactive="true" />
</x-map>

Loading State

Until the map has loaded, a subtle pulsing-dots overlay is shown. It fades out when MapLibre fires load (the map element gets the lm-loaded class). You can replace it, restyle it, or turn it off.

Custom loader

Pass a <x-slot:loading> with any markup. Attributes on the slot (like class) are added to the overlay, which stays centered over the map:

<x-map :center="[-0.1276, 51.5072]" :zoom="11">
    <x-slot:loading class="gap-3">
        <svg class="animate-spin" ...>...</svg>
        <span>Loading London…</span>
    </x-slot:loading>
</x-map>

Restyle the default

The default overlay reads these CSS custom properties, so you can theme it without new markup:

.lm-map {
    --lm-loader-bg: rgba(255, 255, 255, 0.85);  /* overlay background */
    --lm-loader-backdrop: none;                 /* default: blur(2px) */
    --lm-loader-color: #0a0a0a;                 /* dots / text colour */
    --lm-loader-dot-size: 0.5rem;
    --lm-loader-fade: 0.5s;                     /* fade-out duration */
}

Disable it

Use :loader="false" on a single map, or set 'loader' => false in config/livewire-mapcn.php to turn it off everywhere (a map can opt back in with :loader="true"). A <x-slot:loading> is always shown, even when the default loader is disabled. Lazy maps that haven't started yet show their loader as a placeholder until they come into view.

MapLibre Options

Anything without a dedicated prop can be passed straight to the MapLibre Map constructor with :options. These are merged last, so they win over the props.

<x-map
    :options="['hash' => true, 'fadeDuration' => 0, 'maxTileCacheSize' => 200]"
    :attribution-compact="false"
    :loader="false"
/>

Props