mapcn

name	mapcn
description	Technical guide to integrate mapcn in React + shadcn projects. Use when the user asks to integrate mapcn, add mapcn to a shadcn app, use mapcn MapControls/Markers/Routes/Clusters, implement controlled viewport state, use the useMap hook, or access MapLibre through mapcn.

mapcn

When to Use This Skill

Use this skill when the user needs to install, integrate, customize, or troubleshoot mapcn in a React + shadcn/ui codebase.

Typical triggers:

• integrate mapcn
• add mapcn to shadcn project
• mapcn MapControls/Markers/Routes/Clusters
• controlled map viewport with mapcn
• useMap hook mapcn
• MapLibre with mapcn components

Library Overview

mapcn provides copy-paste style map components built on top of MapLibre GL JS and aligned with shadcn/ui workflows.

Assumptions:

• Project uses React.
• Tailwind CSS is already configured.
• shadcn/ui is already configured.

Default behavior:

• mapcn uses free CARTO tiles by default.
• No API key is required for the default tile setup.

Installation

Canonical install command:

npx shadcn@latest add @mapcn/map

Expected integration result:

• UI map components are added to the project (typically under components/ui).
• Import pattern usually follows:

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

Quick Start

Use a fixed-height container and render Map with MapControls.

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

export function BasicMap() {
  return (
    <div className="h-[500px] w-full overflow-hidden rounded-xl border">
      <Map
        initialViewState={{
          longitude: -58.3816,
          latitude: -34.6037,
          zoom: 11,
        }}
      >
        <MapControls
          showZoom
          showCompass
          showLocate
          showFullscreen
          position="top-right"
        />
      </Map>
    </div>
  );
}

Important:

• The map container must have an explicit height, otherwise the map may render blank.

Core Components

Map and Controlled Viewport

Use uncontrolled mode for simple cases, and controlled mode when state synchronization is needed.

const [viewport, setViewport] = useState({
  longitude: -58.3816,
  latitude: -34.6037,
  zoom: 11,
});

<Map viewport={viewport} onViewportChange={setViewport} />

Controls

MapControls supports common toggles and placement:

• showZoom
• showCompass
• showLocate
• showFullscreen
• position

Markers and Marker UI Family

Use marker composition for richer UI:

• MapMarker
• MarkerContent
• MarkerPopup
• MarkerTooltip
• MarkerLabel

Standalone Popups

Use MapPopup for popup UI not strictly attached to a marker component.

Routes

Use MapRoute to draw path-based overlays and route-like lines.

Clusters

Use MapClusterLayer with GeoJSON input for dense point datasets.

Advanced Integration

MapRef

Use MapRef for imperative map actions such as flyTo, custom camera transitions, and direct map instance operations.

useMap

Use useMap to access map context safely and wire event listeners with lifecycle-aware cleanup.

Custom Styles

Use styles prop (or the corresponding map style config option) with MapLibre-compatible style URLs/specs when default tiles are not enough.

Performance Guidelines

• DOM markers are fine for small to medium volumes (typically up to a few hundred points).
• For large datasets, prefer GeoJSON layer-based rendering and clustering (MapClusterLayer).
• Avoid excessive re-renders by stabilizing props and handlers.
• Always clean up event listeners when using advanced map events.

Troubleshooting

Blank Map

Check:

• Container height is explicitly set.
• Style URL/spec is valid.
• Tile requests are not blocked (network/CORS).

Hydration / App Framework Issues

• Ensure map rendering is client-safe in SSR app setups.
• Avoid direct map instance access before mount.

Missing Controls or Markers

• Confirm components are nested under the correct map context.
• Verify expected children hierarchy for marker and popup components.

Type/Coordinate Errors

• Validate coordinate shape/order and prop types.
• Keep callback signatures aligned with component expectations.

Workflow for Agents

1. Detect user intent: install, basic map, markers, popups, routes, clusters, advanced events.
2. Implement the smallest working integration first.
3. Move to controlled viewport only when state sync is required.
4. Switch to cluster/layer patterns when point count grows.
5. Return concise code, then explain decisions and next steps.

Out of Scope

• Non-React frameworks.
• Unrequested wrapper migration/comparison work.
• Hosted map vendor account setup beyond mapcn default/no-key baseline.

References

Local references:

• references/docs-pages.md
• references/api-cheatsheet.md

Canonical docs:

• https://www.mapcn.dev/docs
• https://www.mapcn.dev/docs/installation
• https://www.mapcn.dev/docs/api-reference
• https://www.mapcn.dev/docs/basic-map
• https://www.mapcn.dev/docs/controls
• https://www.mapcn.dev/docs/markers
• https://www.mapcn.dev/docs/popups
• https://www.mapcn.dev/docs/routes
• https://www.mapcn.dev/docs/clusters
• https://www.mapcn.dev/docs/advanced-usage