Preview

Controls

Theme

Surface

Direction

Viewport

Device view renders in an isolated frame so real responsive breakpoints apply. Switch to Full for overflowing popovers.

Installation

terminal

php artisan ui:add map-cluster

Registry contract

Install confidence

php artisan ui:add map-cluster writes only the generated targets below. The CLI validates each file hash before writing and prompts before replacing local changes unless --force is used.

Version: 1.0.0
License: open
Stability: stable
Contract: v2
Foundation: ≥ 1.0.0

Type	Generated target
blade	resources/views/components/ui/map-cluster.blade.php

Registry dependencies

map

Package dependencies

composer: jml/brok:^1.0

Guidance

Geospatial view

Support a decision that depends on geography or distance.

Use when

Use when geography, route, clustering, or distance meaningfully affects decisions. Do not use a map as decoration when location is not central to the task.

Avoid when

Avoid using map-cluster as a default simply because it is available in the library. Choose it only when its interaction cost, visibility, and behavior match the job to be done.

Task length: medium
Interaction cost: high
Interruptiveness: none
Input precision: none
Mobile / touch risk: high
Accessibility risk: high
Needs background context: No
Comparison needed: Yes

Preferred alternatives

Location list or distance table

Anti-patterns

Using a map as decorative scenery

Related: map

API

manifest knowledge + registry-derived coverage

Props

Prop	Type / values	Default	Description
url	mixed\|null	null	Declared by @props in the registry Blade source.
data	mixed\|null	null	Declared by @props in the registry Blade source.
radius	int	50	Declared by @props in the registry Blade source.
maxZoom	int	14	Declared by @props in the registry Blade source.
colors	array	['info', 'primary', 'warning']	Declared by @props in the registry Blade source.
pointColor	string	primary	Declared by @props in the registry Blade source.

Slots

Components use the default Blade slot unless a documented subcomponent is installed by the registry item.

Data slots

map-cluster

Capabilities

wcag-2.2-aa-target responsive rtl darkMode localized

Behavior

Uses server-rendered Blade and semantic HTML.
Declares registry capability flags: a11y, responsive, rtl, darkMode, localized.

Usage

previews.components.map-cluster.default.blade.php Blade

@php
    // Inline demo points (major US metros, jittered) so the cluster animates with
    // no network request. Consumers pass a `url` to a live GeoJSON feed instead.
    $cities = [
        [-74.006, 40.7128], [-73.94, 40.78], [-74.17, 40.74], [-73.79, 40.72],
        [-71.0589, 42.3601], [-71.1, 42.37], [-75.1652, 39.9526], [-77.0369, 38.9072],
        [-76.6122, 39.2904], [-84.388, 33.749], [-80.1918, 25.7617], [-81.3792, 28.5383],
        [-87.6298, 41.8781], [-87.9, 41.97], [-83.0458, 42.3314], [-93.265, 44.9778],
        [-90.1994, 38.627], [-94.5786, 39.0997], [-95.3698, 29.7604], [-96.797, 32.7767],
        [-97.7431, 30.2672], [-98.4936, 29.4241], [-104.9903, 39.7392], [-111.891, 40.7608],
        [-112.074, 33.4484], [-115.1398, 36.1699], [-118.2437, 34.0522], [-117.1611, 32.7157],
        [-122.4194, 37.7749], [-122.3321, 47.6062], [-122.6765, 45.5231],
    ];

    $geojson = [
        'type' => 'FeatureCollection',
        'features' => collect($cities)->map(fn ($c) => [
            'type' => 'Feature',
            'geometry' => ['type' => 'Point', 'coordinates' => $c],
            'properties' => [],
        ])->all(),
    ];
@endphp

<x-ui.map :center="[-96, 38]" :zoom="3" height="420px" label="{{ __('Map clusters') }}">
    <x-ui.map-controls position="top-right" show-zoom />
    <x-ui.map-cluster :data="$geojson" :radius="60" :max-zoom="12" />
</x-ui.map>

Accessibility & localization

WCAG 2.2 AA RTL-ready data-slot Keyboard focus-visible Localized labels

Accessibility target: wcag-2.2-aa-target.
Uses semantic HTML and a stable data-slot attribute for styling/scripting hooks.
Focus-visible rings use the ring token so keyboard focus is always visible.
Disabled and invalid states are conveyed to assistive tech, not by color alone.
Targets WCAG 2.2 AA; verify contrast in light, dark, admin and customer surfaces above.
Labels go through __() and the component uses logical properties (ms-*, text-start, start-*) so it mirrors correctly — flip the preview to RTL to confirm.

Source

The exact, editable file ui:add writes into your app — copy it or own the whole thing. Previews render this same code; there are no preview-only components.

Changelog

Current version: v1.0.0. See the site changelog for the full release history.

Map Cluster