mapcn

https://mapcn.vercel.app/docs
Admin
mapcn provides beautifully designed, accessible, and customizable map components for React built on...
Tokens:10,539
Snippets:75
Trust Score:7.8
Update:1 month ago
Show doc for...
Tokens:
Raw
### Install mapcn component

Source: https://mapcn.vercel.app/docs/installation

Use the shadcn CLI to add the map component to your project.

```bash
pnpm dlx shadcn@latest add @mapcn/map
```

--------------------------------

### Render High-Performance Markers with GeoJSON Layers

Source: https://mapcn.vercel.app/docs/advanced-usage

Use GeoJSON layers to render large datasets on the WebGL canvas for better performance. This example demonstrates source and layer management within a React component.

```typescript
"use client";

import { useEffect, useState, useId } from "react";
import type { MapMouseEvent, MapGeoJSONFeature } from "maplibre-gl";
import { Map, MapPopup, useMap } from "@/components/ui/map";

// Generate random points around NYC
function generateRandomPoints(count: number) {
  const center = { lng: -73.98, lat: 40.75 };
  const features = [];

  for (let i = 0; i < count; i++) {
    const lng = center.lng + (Math.random() - 0.5) * 0.15;
    const lat = center.lat + (Math.random() - 0.5) * 0.1;
    features.push({
      type: "Feature" as const,
      properties: {
        id: i,
        name: `Location ${i + 1}`,
        category: ["Restaurant", "Cafe", "Bar", "Shop"][
          Math.floor(Math.random() * 4)
        ],
      },
      geometry: {
        type: "Point" as const,
        coordinates: [lng, lat],
      },
    });
  }

  return {
    type: "FeatureCollection" as const,
    features,
  };
}

// 200 markers - would be slow with DOM markers, but fast with layers
const pointsData = generateRandomPoints(200);

interface SelectedPoint {
  id: number;
  name: string;
  category: string;
  coordinates: [number, number];
}

function MarkersLayer() {
  const { map, isLoaded } = useMap();
  const id = useId();
  const sourceId = `markers-source-${id}`;
  const layerId = `markers-layer-${id}`;
  const [selectedPoint, setSelectedPoint] = useState<SelectedPoint | null>(
    null,
  );

  useEffect(() => {
    if (!map || !isLoaded) return;

    map.addSource(sourceId, {
      type: "geojson",
      data: pointsData,
    });

    map.addLayer({
      id: layerId,
      type: "circle",
      source: sourceId,
      paint: {
        "circle-radius": 6,
        "circle-color": "#3b82f6",
        "circle-stroke-width": 2,
        "circle-stroke-color": "#ffffff",
        // add more paint properties here to customize the appearance of the markers
      },
    });

    const handleClick = (
      e: MapMouseEvent & {
        features?: MapGeoJSONFeature[];
      },
    ) => {
      if (!e.features?.length) return;

      const feature = e.features[0];
      const coords = (feature.geometry as GeoJSON.Point).coordinates as [
        number,
        number,
      ];

      setSelectedPoint({
        id: feature.properties?.id,
        name: feature.properties?.name,
        category: feature.properties?.category,
        coordinates: coords,
      });
    };

    const handleMouseEnter = () => {
      map.getCanvas().style.cursor = "pointer";
    };

    const handleMouseLeave = () => {
      map.getCanvas().style.cursor = "";
    };

    map.on("click", layerId, handleClick);
    map.on("mouseenter", layerId, handleMouseEnter);
    map.on("mouseleave", layerId, handleMouseLeave);

    return () => {
      map.off("click", layerId, handleClick);
      map.off("mouseenter", layerId, handleMouseEnter);
      map.off("mouseleave", layerId, handleMouseLeave);

      try {
        if (map.getLayer(layerId)) map.removeLayer(layerId);
        if (map.getSource(sourceId)) map.removeSource(sourceId);
      } catch {
        // ignore cleanup errors
      }
    };
  }, [map, isLoaded, sourceId, layerId]);

  return (
    <>
      {selectedPoint && (
        <MapPopup
          longitude={selectedPoint.coordinates[0]}
          latitude={selectedPoint.coordinates[1]}
          onClose={() => setSelectedPoint(null)}
          closeOnClick={false}
          focusAfterOpen={false}
          offset={10}
          closeButton
        >
          <div className="min-w-24">
            <p className="font-medium">{selectedPoint.name}</p>
            <p className="text-muted-foreground text-sm">
              {selectedPoint.category}
            </p>
          </div>
        </MapPopup>
      )}
    </>
  );
}

export function LayerMarkersExample() {
  return (
    <div className="h-[420px] w-full">
      <Map center={[-73.98, 40.75]} zoom={11}>
        <MarkersLayer />
      </Map>
    </div>
  );
}
```

--------------------------------

### Self-host MapLibre Web Worker files

Source: https://mapcn.vercel.app/docs/installation

Copy the required worker files into your public directory to host them locally instead of using unpkg.

```bash
cp node_modules/maplibre-gl/dist/maplibre-gl-worker.mjs \
   node_modules/maplibre-gl/dist/maplibre-gl-shared.mjs \
   public/
```

--------------------------------

### Basic Map Implementation

Source: https://mapcn.vercel.app/docs/basic-map

Initializes a standard interactive map centered at specific coordinates with a defined zoom level.

```typescript
import { Map } from "@/components/ui/map";

export function BasicMapExample() {
  return (
    <div className="h-[420px] w-full">
      <Map center={[-74.006, 40.7128]} zoom={12} />
    </div>
  );
}
```

--------------------------------

### MarkerTooltip

Source: https://mapcn.vercel.app/docs/api-reference

Renders a tooltip that appears on hover. Must be used inside MapMarker.

```APIDOC
## MarkerTooltip

### Description
Renders a tooltip that appears on hover. Must be used inside `MapMarker`. Extends PopupOptions from MapLibre GL.

### Props
- **children** (ReactNode) - Optional - Tooltip content.
- **className** (string) - Optional - Additional CSS classes for the tooltip container.
```

--------------------------------

### Custom Map Styles

Source: https://mapcn.vercel.app/docs/basic-map

Applies custom vector tile styles via the styles prop and demonstrates programmatic camera adjustments using a map reference.

```typescript
"use client";

import { useState, useEffect, useRef } from "react";
import { Map, type MapRef } from "@/components/ui/map";

const styles = {
  default: undefined,
  openstreetmap: "https://tiles.openfreemap.org/styles/bright",
  openstreetmap3d: "https://tiles.openfreemap.org/styles/liberty",
};

type StyleKey = keyof typeof styles;

export function CustomStyleExample() {
  const mapRef = useRef<MapRef>(null);
  const [style, setStyle] = useState<StyleKey>("default");
  const selectedStyle = styles[style];
  const is3D = style === "openstreetmap3d";

  useEffect(() => {
    mapRef.current?.easeTo({ pitch: is3D ? 60 : 0, duration: 500 });
  }, [is3D]);

  return (
    <div className="relative h-[420px] w-full">
      <Map
        ref={mapRef}
        center={[-0.1276, 51.5074]}
        zoom={15}
        styles={
          selectedStyle
            ? { light: selectedStyle, dark: selectedStyle }
            : undefined
        }
      />
      <div className="absolute top-2 right-2 z-10">
        <select
          value={style}
          onChange={(e) => setStyle(e.target.value as StyleKey)}
          className="bg-background text-foreground rounded-md border px-2 py-1 text-sm shadow"
        >
          <option value="default">Default (Carto)</option>
          <option value="openstreetmap">OpenStreetMap</option>
          <option value="openstreetmap3d">OpenStreetMap 3D</option>
        </select>
      </div>
    </div>
  );
}
```

--------------------------------

### Configure CSP for Web Workers

Source: https://mapcn.vercel.app/docs/installation

Add these directives to your Content Security Policy to allow the map component to load the required Web Worker from unpkg.

```text
script-src 'self' https://unpkg.com;
worker-src 'self' blob:;
```

--------------------------------

### Blank Basemap Configuration

Source: https://mapcn.vercel.app/docs/basic-map

Renders a transparent canvas without default tiles, requiring additional layers like GeoJSON to be added as children.

```typescript
import { Map, MapGeoJSON } from "@/components/ui/map";
import { WORLD_GEOJSON } from "@/lib/use-world-data";

export function BlankMapExample() {
  return (
    <div className="h-[420px] w-full">
      {/* `blank` is a transparent canvas — add your own layers on top. */}
      <Map blank center={[10, 25]}>
        <MapGeoJSON data={WORLD_GEOJSON} />
      </Map>
    </div>
  );
}
```

--------------------------------

### Map Component

Source: https://mapcn.vercel.app/docs/api-reference

The root container component that initializes MapLibre GL and provides context to child components. It supports theme switching, custom styles, and controlled viewport management.

```APIDOC
## <Map>

### Description
The root container component that initializes MapLibre GL and provides context to child components. Automatically handles theme switching between light and dark modes.

### Props
- **children** (ReactNode) - Optional - Child components (markers, popups, controls, routes).
- **className** (string) - Optional - Additional CSS classes for the map container.
- **theme** ("light" | "dark") - Optional - Theme for the map. If not provided, automatically detects from document class or system preference.
- **styles** ({ light?: string | StyleSpecification; dark?: string | StyleSpecification }) - Optional - Custom map styles for light and dark themes.
- **blank** (boolean) - Optional - Use a transparent, tile-less basemap instead of the default Carto street basemap.
- **projection** (ProjectionSpecification) - Optional - Map projection type. Use { type: "globe" } for 3D globe view.
- **viewport** (Partial<MapViewport>) - Optional - Controlled viewport state.
- **onViewportChange** ((viewport: MapViewport) => void) - Optional - Callback fired continuously as the viewport changes.
- **loading** (boolean) - Optional - Show a loading indicator on the map.
```

--------------------------------

### Access Map Instance with useMap

Source: https://mapcn.vercel.app/docs/api-reference

Retrieves the MapLibre map instance and loading status. Must be invoked within a Map component context.

```javascript
const { map, isLoaded } = useMap();
```

--------------------------------

### Basic Map Component Usage

Source: https://mapcn.vercel.app/docs/installation

Import the Map and MapControls components to render a map within a card container.

```tsx
import { Map, MapControls } from "@/components/ui/map";
import { Card } from "@/components/ui/card";

export function MyMap() {
  return (
    <Card className="h-[320px] p-0 overflow-hidden">
      <Map center={[-74.006, 40.7128]} zoom={11}>
        <MapControls />
      </Map>
    </Card>
  );
}
```

--------------------------------

### Initialize Map Component Structure

Source: https://mapcn.vercel.app/docs/api-reference

The root Map container component with various child components like markers, popups, and layers.

```jsx
<Map>
  <MapMarker longitude={...} latitude={...}>
    <MarkerContent>
      <MarkerLabel />
    </MarkerContent>
    <MarkerPopup />
    <MarkerTooltip />
  </MapMarker>

  <MapPopup longitude={...} latitude={...} />
  <MapControls />
  <MapRoute coordinates={...} />
  <MapArc data={...} />
  <MapGeoJSON data={...} />
  <MapClusterLayer data={...} />
</Map>
```

--------------------------------

### MapMarker

Source: https://mapcn.vercel.app/docs/api-reference

A container for marker-related components that provides context and handles marker positioning.

```APIDOC
## MapMarker

### Description
A container for marker-related components. Provides context for its children and handles marker positioning. Extends MarkerOptions from MapLibre GL (excluding element).

### Props
- **longitude** (number) - Required - Longitude coordinate for marker position.
- **latitude** (number) - Required - Latitude coordinate for marker position.
- **children** (ReactNode) - Optional - Marker subcomponents (MarkerContent, MarkerPopup, etc).
- **onClick** ((e: MouseEvent) => void) - Optional - Callback when marker is clicked.
- **onMouseEnter** ((e: MouseEvent) => void) - Optional - Callback when mouse enters marker.
- **onMouseLeave** ((e: MouseEvent) => void) - Optional - Callback when mouse leaves marker.
- **onDragStart** ((lngLat: {lng, lat}) => void) - Optional - Callback when marker drag starts (requires draggable: true).
- **onDrag** ((lngLat: {lng, lat}) => void) - Optional - Callback during marker drag (requires draggable: true).
- **onDragEnd** ((lngLat: {lng, lat}) => void) - Optional - Callback when marker drag ends (requires draggable: true).
```

--------------------------------

### MarkerContent

Source: https://mapcn.vercel.app/docs/api-reference

Renders the visual content of a marker. Must be used inside MapMarker.

```APIDOC
## MarkerContent

### Description
Renders the visual content of a marker. Must be used inside `MapMarker`. If no children provided, renders a default blue dot marker.

### Props
- **children** (ReactNode) - Optional - Custom marker content.
- **className** (string) - Optional - Additional CSS classes for the marker container.
```

--------------------------------

### useMap

Source: https://mapcn.vercel.app/docs/api-reference

A hook that provides access to the MapLibre map instance and loading state. Must be used within a Map component.

```APIDOC
## useMap

### Description
A hook that provides access to the MapLibre map instance and loading state. Must be used within a Map component.

### Returns
- **map** (MapLibre.Map) - The map instance.
- **isLoaded** (boolean) - Indicates if the map is loaded and ready to use.
```

--------------------------------

### MapRoute

Source: https://mapcn.vercel.app/docs/api-reference

Renders a line/route on the map connecting coordinate points. Must be used inside Map.

```APIDOC
## MapRoute

### Description
Renders a line/route on the map connecting coordinate points. Must be used inside `Map`. Supports click and hover interactions for building route selection UIs.

### Props
- **id** (string) - Optional unique identifier for the route layer.
- **coordinates** ([number, number][]) - Array of [longitude, latitude] coordinate pairs.
- **color** (string) - Line color (CSS color value). Default: "#4285F4"
- **width** (number) - Line width in pixels. Default: 3
- **opacity** (number) - Line opacity (0 to 1). Default: 0.8
- **dashArray** ([number, number]) - Dash pattern [dash length, gap length] for dashed lines.
- **onClick** (() => void) - Callback when the route line is clicked.
- **onMouseEnter** (() => void) - Callback when mouse enters the route line.
- **onMouseLeave** (() => void) - Callback when mouse leaves the route line.
- **interactive** (boolean) - Respond to mouse events (hover, cursor, callbacks). Default: false
```

--------------------------------

### Render Basic GeoJSON

Source: https://mapcn.vercel.app/docs/geojson

Displays a GeoJSON dataset on a blank map with default styling.

```typescript
import { Map, MapGeoJSON } from "@/components/ui/map";
import { WORLD_GEOJSON } from "@/lib/use-world-data";

export function GeoJSONExample() {
  return (
    <div className="h-[420px] w-full">
      <Map blank center={[10, 25]}>
        <MapGeoJSON data={WORLD_GEOJSON} linePaint={false} />
      </Map>
    </div>
  );
}
```

--------------------------------

### MarkerLabel

Source: https://mapcn.vercel.app/docs/api-reference

Renders a text label above or below a marker. Must be used inside MarkerContent.

```APIDOC
## MarkerLabel

### Description
Renders a text label above or below the marker. Must be used inside `MarkerContent`.

### Props
- **children** (ReactNode) - Label text content.
- **className** (string) - Additional CSS classes for the label.
- **position** ("top" | "bottom") - Position of the label relative to the marker. Default: "top"
```

--------------------------------

### MarkerPopup

Source: https://mapcn.vercel.app/docs/api-reference

Renders a popup attached to the marker that opens on click. Must be used inside MapMarker.

```APIDOC
## MarkerPopup

### Description
Renders a popup attached to the marker that opens on click. Must be used inside `MapMarker`. Extends PopupOptions from MapLibre GL.

### Props
- **children** (ReactNode) - Optional - Popup content.
- **className** (string) - Optional - Additional CSS classes for the popup container.
- **closeButton** (boolean) - Optional - Show a close button in the popup (default: false).
```

--------------------------------

### MapControls

Source: https://mapcn.vercel.app/docs/api-reference

Renders map control buttons such as zoom, compass, locate, and fullscreen. Must be used inside a Map component.

```APIDOC
## MapControls

### Description
Renders map control buttons (zoom, compass, locate, fullscreen). Must be used inside Map.

### Props
- **position** ("top-left" | "top-right" | "bottom-left" | "bottom-right") - Optional - Position of the controls on the map. Default: "bottom-right".
- **showZoom** (boolean) - Optional - Show zoom in/out buttons. Default: true.
- **showCompass** (boolean) - Optional - Show compass button to reset bearing. Default: false.
- **showLocate** (boolean) - Optional - Show locate button to find user's location. Default: false.
- **showFullscreen** (boolean) - Optional - Show fullscreen toggle button. Default: false.
- **className** (string) - Optional - Additional CSS classes for the controls container.
- **onLocate** ((coords: { longitude: number; latitude: number }) => void) - Optional - Callback with user coordinates when located.
```

--------------------------------

### Implement Custom Map Controls in React

Source: https://mapcn.vercel.app/docs/advanced-usage

Uses the useMap hook to access map instances and event listeners for real-time state updates. Requires the map to be fully loaded before attaching event handlers.

```typescript
"use client";

import { useEffect, useState } from "react";
import { Map, useMap } from "@/components/ui/map";
import { Button } from "@/components/ui/button";
import { RotateCcw, Mountain } from "lucide-react";

function MapController() {
  const { map, isLoaded } = useMap();
  const [pitch, setPitch] = useState(0);
  const [bearing, setBearing] = useState(0);

  useEffect(() => {
    if (!map || !isLoaded) return;

    const handleMove = () => {
      setPitch(Math.round(map.getPitch()));
      setBearing(Math.round(map.getBearing()));
    };

    map.on("move", handleMove);
    return () => {
      map.off("move", handleMove);
    };
  }, [map, isLoaded]);

  const handle3DView = () => {
    map?.easeTo({
      pitch: 60,
      bearing: -20,
      duration: 1000,
    });
  };

  const handleReset = () => {
    map?.easeTo({
      pitch: 0,
      bearing: 0,
      duration: 1000,
    });
  };

  if (!isLoaded) return null;

  return (
    <div className="absolute top-3 left-3 z-10 flex flex-col gap-2">
      <div className="flex gap-2">
        <Button size="sm" variant="secondary" onClick={handle3DView}>
          <Mountain className="mr-1.5 size-4" />
          3D View
        </Button>
        <Button size="sm" variant="secondary" onClick={handleReset}>
          <RotateCcw className="mr-1.5 size-4" />
          Reset
        </Button>
      </div>
      <div className="bg-background/90 rounded-md border px-3 py-2 font-mono text-xs backdrop-blur">
        <div>Pitch: {pitch}°</div>
        <div>Bearing: {bearing}°</div>
      </div>
    </div>
  );
}

export function AdvancedUsageExample() {
  return (
    <div className="h-[420px] w-full">
      <Map center={[-73.9857, 40.7484]} zoom={15}>
        <MapController />
      </Map>
    </div>
  );
}
```

--------------------------------

### Implement Custom GeoJSON Layer with Interactions

Source: https://mapcn.vercel.app/docs/advanced-usage

Uses React hooks to manage map layers and hover states for GeoJSON features. Requires the map context to be available via the useMap hook.

```typescript
"use client";

import { useCallback, useEffect, useState } from "react";
import type { MapMouseEvent } from "maplibre-gl";
import { Map, MapControls, useMap } from "@/components/ui/map";
import { Button } from "@/components/ui/button";
import { Layers, X } from "lucide-react";

const geojsonData = {
  type: "FeatureCollection" as const,
  features: [
    {
      type: "Feature" as const,
      properties: { name: "Central Park", type: "park" },
      geometry: {
        type: "Polygon" as const,
        coordinates: [
          [
            [-73.9731, 40.7644],
            [-73.9819, 40.7681],
            [-73.958, 40.8006],
            [-73.9493, 40.7969],
            [-73.9731, 40.7644],
          ],
        ],
      },
    },
    {
      type: "Feature" as const,
      properties: { name: "Bryant Park", type: "park" },
      geometry: {
        type: "Polygon" as const,
        coordinates: [
          [
            [-73.9837, 40.7536],
            [-73.9854, 40.7542],
            [-73.984, 40.7559],
            [-73.9823, 40.7553],
            [-73.9837, 40.7536],
          ],
        ],
      },
    },
  ],
};

function CustomLayer() {
  const { map, isLoaded } = useMap();
  const [isLayerVisible, setIsLayerVisible] = useState(false);
  const [hoveredPark, setHoveredPark] = useState<string | null>(null);

  const addLayers = useCallback(() => {
    if (!map) return;
    // Add source if it doesn't exist
    if (!map.getSource("parks")) {
      map.addSource("parks", {
        type: "geojson",
        data: geojsonData,
      });
    }

    // Add fill layer if it doesn't exist
    if (!map.getLayer("parks-fill")) {
      map.addLayer({
        id: "parks-fill",
        type: "fill",
        source: "parks",
        paint: {
          "fill-color": "#22c55e",
          "fill-opacity": 0.4,
        },
        layout: {
          visibility: isLayerVisible ? "visible" : "none",
        },
      });
    }

    // Add outline layer if it doesn't exist
    if (!map.getLayer("parks-outline")) {
      map.addLayer({
        id: "parks-outline",
        type: "line",
        source: "parks",
        paint: {
          "line-color": "#16a34a",
          "line-width": 2,
        },
        layout: {
          visibility: isLayerVisible ? "visible" : "none",
        },
      });
    }
  }, [map, isLayerVisible]);

  useEffect(() => {
    if (!map || !isLoaded) return;

    // Add layers on mount
    addLayers();

    // Hover effect
    const handleMouseEnter = () => {
      map.getCanvas().style.cursor = "pointer";
    };

    const handleMouseLeave = () => {
      map.getCanvas().style.cursor = "";
      setHoveredPark(null);
    };

    const handleMouseMove = (e: MapMouseEvent) => {
      const features = map.queryRenderedFeatures(e.point, {
        layers: ["parks-fill"],
      });
      if (features.length > 0) {
        setHoveredPark(features[0].properties?.name || null);
      }
    };

    map.on("mouseenter", "parks-fill", handleMouseEnter);
    map.on("mouseleave", "parks-fill", handleMouseLeave);
    map.on("mousemove", "parks-fill", handleMouseMove);

    return () => {
      map.off("mouseenter", "parks-fill", handleMouseEnter);
      map.off("mouseleave", "parks-fill", handleMouseLeave);
      map.off("mousemove", "parks-fill", handleMouseMove);
    };
  }, [map, isLoaded, isLayerVisible]);

  const toggleLayer = () => {
    if (!map) return;

    const visibility = isLayerVisible ? "none" : "visible";
    map.setLayoutProperty("parks-fill", "visibility", visibility);
    map.setLayoutProperty("parks-outline", "visibility", visibility);
    setIsLayerVisible(!isLayerVisible);
  };

  return (
    <>
      <div className="absolute top-3 left-3 z-10">
        <Button
          size="sm"
          variant={isLayerVisible ? "default" : "secondary"}
          onClick={toggleLayer}
        >
          {isLayerVisible ? (
            <X className="mr-1.5 size-4" />
          ) : (
            <Layers className="mr-1.5 size-4" />
          )}
          {isLayerVisible ? "Hide Parks" : "Show Parks"}
        </Button>
      </div>

      {hoveredPark && (
        <div className="bg-background/90 absolute bottom-3 left-3 z-10 rounded-md border px-3 py-2 text-sm font-medium backdrop-blur">
          {hoveredPark}
        </div>
      )}
    </>
  );
}

export function CustomLayerExample() {
  return (
    <div className="h-[420px] w-full">
      <Map center={[-73.97, 40.78]} zoom={11.8}>
        <MapControls />
        <CustomLayer />
      </Map>
    </div>
  );
}
```

--------------------------------

### Basic MapControls Implementation

Source: https://mapcn.vercel.app/docs/controls

Integrates MapControls into a Map component with specific positioning and enabled features.

```tsx
import { Map, MapControls } from "@/components/ui/map";

export function MapControlsExample() {
  return (
    <div className="h-[420px] w-full">
      <Map center={[2.3522, 48.8566]} zoom={10}>
        <MapControls
          position="top-right"
          showZoom
          showCompass
          showLocate
          showFullscreen
        />
      </Map>
    </div>
  );
}
```

--------------------------------

### MapPopup

Source: https://mapcn.vercel.app/docs/api-reference

A standalone popup component that can be placed anywhere on the map without a marker. Must be used inside Map.

```APIDOC
## MapPopup

### Description
A standalone popup component that can be placed anywhere on the map without a marker. Must be used inside `Map`.

### Props
- **longitude** (number) - Longitude coordinate for popup position.
- **latitude** (number) - Latitude coordinate for popup position.
- **onClose** (() => void) - Callback when popup is closed.
- **children** (ReactNode) - Popup content.
- **className** (string) - Additional CSS classes for the popup container.
- **closeButton** (boolean) - Show a close button in the popup. Default: false
```

--------------------------------

### Access Map Instance via Ref

Source: https://mapcn.vercel.app/docs/advanced-usage

Use a React ref to directly call MapLibre GL methods from event handlers or effects.

```typescript
import { Map, type MapRef } from "@/components/ui/map";
import { useRef } from "react";

function MyMapComponent() {
  const mapRef = useRef<MapRef>(null);

  const handleFlyTo = () => {
    // Access the MapLibre GL map instance via ref
    mapRef.current?.flyTo({ center: [-74, 40.7], zoom: 12 });
  };

  return (
    <>
      <button onClick={handleFlyTo}>Fly to NYC</button>
      <Map ref={mapRef} center={[-74, 40.7]} zoom={10} />
    </>
  );
}
```

--------------------------------

### Set custom worker URL

Source: https://mapcn.vercel.app/docs/installation

Update the component configuration to point to the locally hosted worker file.

```tsx
MapLibreGL.setWorkerUrl("/maplibre-gl-worker.mjs");
```

--------------------------------

### Access Map Instance via useMap Hook

Source: https://mapcn.vercel.app/docs/advanced-usage

Utilize the useMap hook within child components to access the map instance and manage event listeners.

```typescript
import { Map, useMap } from "@/components/ui/map";
import { useEffect } from "react";

// For child components inside Map, use the useMap hook
function MapEventListener() {
  const { map, isLoaded } = useMap();

  useEffect(() => {
    if (!map || !isLoaded) return;
    
    const handleClick = (e) => {
      console.log("Clicked at:", e.lngLat);
    };

    map.on("click", handleClick);
    return () => map.off("click", handleClick);
  }, [map, isLoaded]);

  return null;
}

// Usage
<Map center={[-74, 40.7]} zoom={10}>
  <MapEventListener />
</Map>
```

--------------------------------

### Overlay GeoJSON on a Map

Source: https://mapcn.vercel.app/docs/geojson

Renders a custom GeoJSON polygon with specific fill and line paint properties over a standard map.

```typescript
import { Map, MapGeoJSON } from "@/components/ui/map";

// Inline GeoJSON polygon covering a downtown area.
const area: GeoJSON.FeatureCollection = {
  type: "FeatureCollection",
  features: [
    {
      type: "Feature",
      properties: {},
      geometry: {
        type: "Polygon",
        coordinates: [
          [
            [-122.42, 37.78],
            [-122.398, 37.785],
            [-122.392, 37.768],
            [-122.412, 37.758],
            [-122.43, 37.77],
            [-122.42, 37.78],
          ],
        ],
      },
    },
  ],
};

export function MapOverlayExample() {
  return (
    <div className="h-[420px] w-full">
      {/* Default basemap with a translucent GeoJSON polygon on top. */}
      <Map center={[-122.41, 37.772]} zoom={12}>
        <MapGeoJSON
          data={area}
          fillPaint={{ "fill-color": "#3b82f6", "fill-opacity": 0.25 }}
          linePaint={{ "line-color": "#2563eb", "line-width": 2 }}
        />
      </Map>
    </div>
  );
}
```

--------------------------------

### MapGeoJSON Component

Source: https://mapcn.vercel.app/docs/api-reference

The MapGeoJSON component renders GeoJSON data as fill and outline layers within a Map context.

```APIDOC
## MapGeoJSON

### Description
Renders arbitrary GeoJSON as fill and outline layers. Must be used inside a Map component.

### Props
- **data** (FeatureCollection | Feature | Geometry | string) - Required - GeoJSON data or a URL string to fetch it from.
- **id** (string) - Optional - Id prefix for the underlying source/layers.
- **promoteId** (string) - Optional - Feature property to promote to the feature id. Required for hover feature-state.
- **fillPaint** (FillLayerSpecification['paint'] | false) - Optional - Paint for the polygon fill layer.
- **linePaint** (LineLayerSpecification['paint'] | false) - Optional - Paint for the outline layer.
- **fillHoverPaint** (FillLayerSpecification['paint']) - Optional - Paint merged onto the fill layer for the hovered feature.
- **onClick** ((e: MapGeoJSONEvent) => void) - Optional - Fired when a feature is clicked.
- **onHover** ((e: MapGeoJSONEvent | null) => void) - Optional - Fired when the hovered feature changes.
- **interactive** (boolean) - Optional - Respond to mouse events.
- **beforeId** (string) - Optional - Insert the layers before this layer id.
```

--------------------------------

### Implement MapClusterLayer in React

Source: https://mapcn.vercel.app/docs/clusters

Displays earthquake data using MapClusterLayer with custom popup interaction for individual points.

```tsx
"use client";

import { useState } from "react";
import { Map, MapClusterLayer, MapPopup, MapControls } from "@/components/ui/map";

interface EarthquakeProperties {
  mag: number;
  place: string;
  tsunami: number;
}

export default function ClusterExample() {
  const [selectedPoint, setSelectedPoint] = useState<{
    coordinates: [number, number];
    properties: EarthquakeProperties;
  } | null>(null);

  return (
    <div className="h-[420px] w-full">
      <Map center={[-103.59, 40.66]} zoom={3.4} fadeDuration={0}>
        <MapClusterLayer<EarthquakeProperties>
          data="https://maplibre.org/maplibre-gl-js/docs/assets/earthquakes.geojson"
          clusterRadius={50}
          clusterMaxZoom={14}
          onPointClick={(feature, coordinates) => {
            setSelectedPoint({
              coordinates,
              properties: feature.properties,
            });
          }}
        />

        {selectedPoint && (
          <MapPopup
            key={`${selectedPoint.coordinates[0]}-${selectedPoint.coordinates[1]}`}
            longitude={selectedPoint.coordinates[0]}
            latitude={selectedPoint.coordinates[1]}
            onClose={() => setSelectedPoint(null)}
            closeOnClick={false}
            focusAfterOpen={false}
            closeButton
            className="w-34"
          >
            <div className="text-[13px]">
              <p className="text-muted-foreground">
                Magnitude:{" "}
                <span className="text-foreground font-medium">
                  {selectedPoint.properties.mag}
                </span>
              </p>
              <p className="text-muted-foreground">
                Tsunami:{" "}
                <span className="text-foreground">
                  {selectedPoint.properties?.tsunami === 1 ? "Yes" : "No"}
                </span>
              </p>
            </div>
          </MapPopup>
        )}

        <MapControls />
      </Map>
    </div>
  );
}
```

--------------------------------

### MapClusterLayer

Source: https://mapcn.vercel.app/docs/api-reference

A component for rendering clustered point data. It must be used as a child of the Map component.

```APIDOC
## MapClusterLayer

### Description
Renders clustered point data using MapLibre GL's native clustering. Automatically groups nearby points into clusters that expand on click. Must be used inside `Map`.

### Props
- **data** (string | GeoJSON.FeatureCollection) - Required - GeoJSON FeatureCollection data or URL to fetch GeoJSON from.
- **clusterMaxZoom** (number) - Optional - Maximum zoom level to cluster points on. Default: 14.
- **clusterRadius** (number) - Optional - Radius of each cluster when clustering points (in pixels). Default: 50.
- **clusterColors** ([string, string, string]) - Optional - Colors for cluster circles: [small, medium, large] based on point count. Default: ["#3b82f6", "#1d4ed8", "#1e3a8a"].
- **clusterThresholds** ([number, number]) - Optional - Point count thresholds for color/size steps: [medium, large]. Default: [100, 750].
- **pointColor** (string) - Optional - Color for unclustered individual points. Default: "#3b82f6".
- **onPointClick** ((feature: GeoJSON.Feature, coordinates: [number, number]) => void) - Optional - Callback when an unclustered point is clicked.
- **onClusterClick** ((clusterId: number, coordinates: [number, number], pointCount: number) => void) - Optional - Callback when a cluster is clicked. If not provided, zooms into the cluster.
```

--------------------------------

### Controlled Map Viewport

Source: https://mapcn.vercel.app/docs/basic-map

Manages the map's viewport state externally using React state, allowing for synchronization with application UI.

```typescript
"use client";

import { useState } from "react";
import { Map, type MapViewport } from "@/components/ui/map";

export function ControlledMapExample() {
  const [viewport, setViewport] = useState<MapViewport>({
    center: [-74.006, 40.7128],
    zoom: 8,
    bearing: 0,
    pitch: 0,
  });

  return (
    <div className="relative h-[420px] w-full">
      <Map viewport={viewport} onViewportChange={setViewport} />
      <div className="bg-background/80 absolute top-2 left-2 z-10 flex flex-wrap gap-x-3 gap-y-1 rounded border px-2 py-1.5 font-mono text-xs backdrop-blur">
        <span>
          <span className="text-muted-foreground">lng:</span>{" "}
          {viewport.center[0].toFixed(3)}
        </span>
        <span>
          <span className="text-muted-foreground">lat:</span>{" "}
          {viewport.center[1].toFixed(3)}
        </span>
        <span>
          <span className="text-muted-foreground">zoom:</span>{" "}
          {viewport.zoom.toFixed(1)}
        </span>
        <span>
          <span className="text-muted-foreground">bearing:</span>{" "}
          {viewport.bearing.toFixed(1)}°
        </span>
        <span>
          <span className="text-muted-foreground">pitch:</span>{" "}
          {viewport.pitch.toFixed(1)}°
        </span>
      </div>
    </div>
  );
}
```

--------------------------------

### MapArc Component

Source: https://mapcn.vercel.app/docs/api-reference

The MapArc component renders curved lines between coordinate pairs. It supports interactive features and custom styling using MapLibre layer specifications.

```APIDOC
## MapArc

### Description
Renders curved lines between coordinate pairs using a quadratic Bézier in longitude/latitude space. Must be used inside `Map`.

### Props
- **data** (MapArcDatum[]) - Required - Arcs to render. Each needs a unique id and from / to as [lng, lat].
- **id** (string) - Optional - Id prefix for the underlying source/layers.
- **curvature** (number) - Optional - How far the arc bows away from a straight line.
- **samples** (number) - Optional - Points per arc.
- **paint** (LineLayerSpecification['paint']) - Optional - Paint props merged over defaults.
- **layout** (LineLayerSpecification['layout']) - Optional - Layout props merged over defaults.
- **hoverPaint** (LineLayerSpecification['paint']) - Optional - Paint overrides applied to the hovered arc.
- **onClick** ((e: MapArcEvent) => void) - Optional - Fired when an arc is clicked.
- **onHover** ((e: MapArcEvent | null) => void) - Optional - Fired when the hovered arc changes.
- **interactive** (boolean) - Optional - Respond to mouse events.
- **beforeId** (string) - Optional - Insert the arc layers before this layer id.
```
Tokens:
Raw