# Map
URL: /docs/web/components/map

Interactive map component built on Leaflet with SSR-safe lazy loading, theme-aware tiles, marker clustering, drawing tools, custom controls, and geolocation.

**Demo:**

```tsx
'use client';

import { useState } from 'react';

import { type LatLngExpression } from 'leaflet';

import {
  Map,
  MapDrawCircle,
  MapDrawControl,
  MapDrawDelete,
  MapDrawEdit,
  MapDrawMarker,
  MapDrawPolygon,
  MapDrawPolyline,
  MapDrawRectangle,
  MapDrawUndo,
  MapFullscreenControl,
  MapLocateControl,
  MapMarker,
  MapPopup,
  MapTileLayer,
  MapTooltip,
  MapZoomControl
} from '@docyrus/ui/components/map';
import { Switch } from '@docyrus/ui/primitives/ui/switch';
import { cn } from '@docyrus/ui/primitives/lib/utils';

const SF_CENTER: LatLngExpression = [37.7749, -122.4194];

interface MarkerData {
  position: LatLngExpression;
  title: string;
  description: string;
}

const MARKERS: MarkerData[] = [
  {
    position: [37.7749, -122.4194],
    title: 'San Francisco',
    description: 'City by the Bay'
  },
  {
    position: [37.8024, -122.4058],
    title: 'Fisherman\'s Wharf',
    description: 'Popular waterfront neighborhood'
  },
  {
    position: [37.7956, -122.3933],
    title: 'Financial District',
    description: 'Business center of San Francisco'
  }
];

export function MapDemo() {
  const [showControls, setShowControls] = useState(true);
  const [showDraw, setShowDraw] = useState(false);
  const [open, setOpen] = useState(false);

  return (
    <div className="w-full">
      <div className="mb-3 flex justify-end">
        <button
          type="button"
          className="inline-flex items-center gap-1.5 rounded-md border border-border bg-background px-3 py-1.5 text-sm font-medium transition-colors hover:bg-accent"
          onClick={() => setOpen(prev => !prev)}>
          <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z" /><circle cx="12" cy="12" r="3" /></svg>
          Configure
          <svg xmlns="http://www.w3.org/2000/svg" width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" className={cn('transition-transform duration-200', open && 'rotate-180')}><path d="m6 9 6 6 6-6" /></svg>
        </button>
      </div>
      <div
        className={cn(
          'grid transition-[grid-template-rows] duration-300 ease-in-out',
          open ? 'grid-rows-[1fr]' : 'grid-rows-[0fr]'
        )}>
        <div className="overflow-hidden">
          <div className="mb-4 grid gap-6 rounded-lg border border-border bg-muted/30 p-4">
            <div className="flex flex-wrap items-center gap-4">
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Zoom / Fullscreen / Locate</span>
              </label>
              <label className="flex items-center gap-2">
                
                <span className="text-xs">Draw tools</span>
              </label>
            </div>
          </div>
        </div>
      </div>
      <div className="overflow-hidden rounded-lg border border-border">
        
              
            
          ))}

          {showControls && (
            <>
              
              
              
            </>
          )}

          {showDraw && (
            
          )}
        
      </div>
    </div>
  );
}
```

## Installation

```bash
pnpm dlx @docyrus/cli add @docyrus/ui-map
```

**Dependencies:**
- [leaflet-draw](https://www.npmjs.com/package/leaflet-draw)
- [leaflet](https://www.npmjs.com/package/leaflet)
- [leaflet.markercluster](https://www.npmjs.com/package/leaflet.markercluster)
- [lucide-react](https://www.npmjs.com/package/lucide-react)
- [react-dom](https://www.npmjs.com/package/react-dom)
- [react-leaflet](https://www.npmjs.com/package/react-leaflet)
- [react-leaflet-markercluster](https://www.npmjs.com/package/react-leaflet-markercluster)

## Usage

```tsx
import {
  Map,
  MapTileLayer,
  MapMarker,
  MapPopup,
  MapZoomControl,
  useLeaflet
} from '@docyrus/ui/components/map';

  

```

### With Layers & Clustering

```tsx
import {
  Map,
  MapTileLayer,
  MapLayers,
  MapLayerGroup,
  MapLayersControl,
  MapMarker,
  MapMarkerClusterGroup,
  MapZoomControl
} from '@docyrus/ui/components/map';

    
    
  
  

```

### With Drawing Tools

```tsx
import {
  Map,
  MapTileLayer,
  MapDrawControl,
  MapDrawMarker,
  MapDrawPolyline,
  MapDrawPolygon,
  MapDrawCircle,
  MapDrawRectangle,
  MapDrawEdit,
  MapDrawDelete,
  MapDrawUndo
} from '@docyrus/ui/components/map';

```

### Dark Mode Tile Layers

`MapTileLayer` supports separate `url` and `darkUrl` props. Theme detection uses `useDocyTheme` automatically.

```tsx

```

## Components

| Component | Description |
|-----------|-------------|
| `Map` | Root container. Wraps Leaflet `MapContainer` with SSR-safe lazy loading. |
| `MapTileLayer` | Tile layer with dark mode support via `darkUrl`. |
| `MapLayers` | Context provider for tile layer and layer group management. |
| `MapLayerGroup` | Named layer group that registers with `MapLayers`. |
| `MapFeatureGroup` | Feature group that registers with `MapLayers`. |
| `MapLayersControl` | Dropdown to select tile layers and toggle layer groups. |
| `MapMarker` | Marker with custom `ReactNode` icon via `DivIcon`. |
| `MapMarkerClusterGroup` | Cluster group with custom badge icon function. |
| `MapCircle` | Circle shape overlay. |
| `MapCircleMarker` | Circle marker overlay. |
| `MapPolyline` | Polyline shape overlay. |
| `MapPolygon` | Polygon shape overlay. |
| `MapRectangle` | Rectangle shape overlay. |
| `MapPopup` | Styled popup with dark mode support. |
| `MapTooltip` | Tooltip with directional arrow. |
| `MapControlContainer` | Container for custom controls (disables map interaction propagation). |
| `MapZoomControl` | Zoom in/out buttons. |
| `MapFullscreenControl` | Fullscreen toggle button. |
| `MapLocateControl` | Geolocation tracker with optional watch mode. |
| `MapSearchControl` | Place search via `PlaceAutocomplete` integration. |
| `MapDrawControl` | Context provider for drawing mode. |
| `MapDrawMarker` | Toggle button for marker drawing. |
| `MapDrawPolyline` | Toggle button for polyline drawing. |
| `MapDrawCircle` | Toggle button for circle drawing. |
| `MapDrawRectangle` | Toggle button for rectangle drawing. |
| `MapDrawPolygon` | Toggle button for polygon drawing. |
| `MapDrawEdit` | Toggle button for editing drawn shapes. |
| `MapDrawDelete` | Toggle button for deleting drawn shapes. |
| `MapDrawUndo` | Undo last edit/delete action. |
| `useLeaflet` | Hook to lazy-load Leaflet + plugins. Returns `{ L, ready }`. |

## API Reference

### Map

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `center` | `LatLngExpression` | — | Map center coordinates. |
| `zoom` | `number` | `15` | Initial zoom level. |
| `maxZoom` | `number` | `18` | Maximum zoom level. |
| `className` | `string` | — | Additional CSS classes. |

### MapTileLayer

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | `'Default'` | Layer identifier for `MapLayersControl`. |
| `url` | `string` | OpenStreetMap URL | Tile URL template. |
| `darkUrl` | `string` | — | Dark theme tile URL. Auto-switches with `useDocyTheme`. |
| `attribution` | `string` | — | Attribution text for light theme. |
| `darkAttribution` | `string` | — | Attribution text for dark theme. |

### MapLayers

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `defaultTileLayer` | `string` | — | Initial active tile layer name. |
| `defaultLayerGroups` | `string[]` | `[]` | Initially visible layer group names. |

### MapLayerGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `name` | `string` | — | Layer group identifier. |
| `disabled` | `boolean` | — | Hide from layer controls toggle. |

### MapMarker

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `LatLngExpression` | — | Marker coordinates. |
| `icon` | `ReactNode` | `` | Custom icon rendered as `DivIcon`. |
| `iconAnchor` | `[number, number]` | `[12, 12]` | Icon anchor point. |
| `popupAnchor` | `[number, number]` | — | Popup anchor offset. |
| `tooltipAnchor` | `[number, number]` | — | Tooltip anchor offset. |

### MapMarkerClusterGroup

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `icon` | `(count: number) => ReactNode` | — | Custom cluster badge render function. |
| `polygonOptions` | `object` | — | Cluster boundary polygon styling. |

### MapLayersControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `string` | `'top-1 right-1'` | Tailwind position classes. |
| `tileLayersLabel` | `string` | `'Map Type'` | Section label for tile layers. |
| `layerGroupsLabel` | `string` | `'Layers'` | Section label for layer groups. |

### MapTooltip

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `side` | `'top' \| 'right' \| 'bottom' \| 'left'` | `'top'` | Arrow direction. |
| `sideOffset` | `number` | `15` | Distance from target element. |

### MapZoomControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `string` | `'top-1 left-1'` | Tailwind position classes. |

### MapFullscreenControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `position` | `string` | `'top-1 right-1'` | Tailwind position classes. |

### MapLocateControl

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `watch` | `boolean` | `false` | Continuously track location. |
| `onLocationFound` | `(event: LocationEvent) => void` | — | Called when location is found. |
| `onLocationError` | `(error: ErrorEvent) => void` | — | Called on location error. |
| `position` | `string` | `'right-1 bottom-1'` | Tailwind position classes. |

### MapSearchControl

Inherits all props from `PlaceAutocomplete`. Renders a search input on the map.

### MapDrawControl

Container for drawing tool buttons. Provides drawing mode context.

| Prop | Type | Default | Description |
|------|------|---------|-------------|
| `className` | `string` | — | Additional CSS classes. |

### useLeaflet

Hook that lazy-loads the Leaflet library and its plugins.

```tsx
const { L, ready } = useLeaflet();
if (!ready) return ;
```

Returns `{ L: typeof Leaflet, ready: boolean }`.