Map

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

Edit on GitHubEditllms.txt

Client Only

Installation

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

UI Primitives(3 components)

npx shadcn@latest add button button-group dropdown-menu

Required Packages(6 packages)

pnpm add leaflet-draw leaflet leaflet.markercluster react-dom react-leaflet react-leaflet-markercluster

Usage

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

<Map center={[41.0082, 28.9784]} zoom={13}>
  <MapTileLayer />
  <MapZoomControl />
  <MapMarker position={[41.0082, 28.9784]}>
    <MapPopup>Istanbul</MapPopup>
  </MapMarker>
</Map>

With Layers & Clustering

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

<Map center={[41.0082, 28.9784]} zoom={13}>
  <MapLayers defaultTileLayer="Default" defaultLayerGroups={['markers']}>
    <MapTileLayer name="Default" />
    <MapTileLayer
      name="Satellite"
      url="https://..."
      darkUrl="https://..."
    />
    <MapLayerGroup name="markers">
      <MapMarkerClusterGroup>
        {markers.map(m => (
          <MapMarker key={m.id} position={m.position} />
        ))}
      </MapMarkerClusterGroup>
    </MapLayerGroup>
    <MapLayersControl />
  </MapLayers>
  <MapZoomControl />
</Map>

With Drawing Tools

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

<Map center={[41.0082, 28.9784]} zoom={13}>
  <MapTileLayer />
  <MapDrawControl>
    <MapDrawMarker />
    <MapDrawPolyline />
    <MapDrawPolygon />
    <MapDrawCircle />
    <MapDrawRectangle />
    <MapDrawEdit />
    <MapDrawDelete />
    <MapDrawUndo />
  </MapDrawControl>
</Map>

Dark Mode Tile Layers

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

<MapTileLayer
  name="Streets"
  url="https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png"
  darkUrl="https://tiles.stadiamaps.com/tiles/alidade_smooth_dark/{z}/{x}/{y}.png"
/>

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`	`<MapPinIcon />`	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.

const { L, ready } = useLeaflet();
if (!ready) return <Spinner />;

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

Map

On this page