mapcn: How to Add Interactive Maps to React Applications (Installation & Guide)

If you are building a React application that needs interactive maps, markers, location popups, or route visualization, setting everything up manually can take time.

mapcn makes this process easier by providing ready-to-use, customizable map components built with MapLibre GL. It follows the shadcn/ui approach, allowing developers to add map components directly to their projects and customize the code according to their requirements.

In this guide, we will explore what mapcn does, its main features, how to install it, and how to create your first interactive map in a React application.

What Is mapcn?

mapcn is a free and open-source collection of map components for React developers. It is built on MapLibre GL, styled with Tailwind CSS, and designed to work with shadcn/ui.

Instead of building every map element from scratch, developers can install individual components and use them in their applications.

One of its main advantages is its copy-and-customize approach. The components become part of your project, so you can modify their code and styling whenever needed.

mapcn supports interactive maps, markers, popups, tooltips, route drawing, map controls, GeoJSON layers, and more.

Official resources:

GitHub Repository: https://github.com/AnmolSaini16/mapcn
Official Website: https://www.mapcn.dev/
Documentation: https://www.mapcn.dev/docs

Key Features of mapcn

Here are some of the features that make mapcn useful for React development.

1. Ready-to-Use Map Components

mapcn provides customizable map components that developers can add directly to their applications. It uses sensible defaults, so you can get started without manually configuring every map element.

2. Interactive Markers and Popups

You can add markers to identify specific locations on a map. Markers can also display additional information through popups, tooltips, and labels.

This is useful for store locators, travel applications, delivery dashboards, and location-based platforms.

3. Route Visualization

The route components allow developers to draw paths between different locations. You can use them to display delivery routes, travel directions, and connections between places.

4. Map Controls

mapcn includes controls for common map interactions, such as:

Zooming in and out.
Changing map orientation with compass controls.
Locating the user's position.
Switching to fullscreen mode.

5. Light and Dark Theme Support

The map automatically adapts to light and dark themes. Its default CARTO map styles also switch between themes, helping the map fit naturally into your application's interface.

6. GeoJSON and Map Clustering

Developers can work with GeoJSON data to display geographical information and use clustering to organize groups of markers.

These features can be useful when building applications that display many locations or geographical datasets.

7. AI Coding Agent Support

Another interesting feature is its dedicated agent skill.

You can install the mapcn skill using a single command:

npx skills add AnmolSaini16/mapcn

This gives compatible AI coding agents, including Claude Code, Cursor, and Codex, instructions for working with mapcn.

You can then ask your coding agent to add a map to your application or suggest where map components could be useful.

How to Install mapcn in a React Project

Before installing mapcn, you should have a React project configured with Tailwind CSS and shadcn/ui.

Follow these steps to get started.

Step 1: Open Your Project

Open your existing React or Next.js project in your code editor.

Make sure you have Node.js and a package manager installed.

You should also have Tailwind CSS and shadcn/ui configured in your project.

Step 2: Install the Map Component

Open your terminal and run the following command:

npx shadcn@latest add @mapcn/map

If you use pnpm, you can run:

pnpm dlx shadcn@latest add @mapcn/map

This command installs the MapLibre GL dependency and adds the map component to your project.

The component is generally added to:

components/ui/map.tsx

Step 3: Import the Map Components

After installation, import the components into the React file where you want to display your map.

For example:

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

You can now use these components to create an interactive map.

Step 4: Create Your First Interactive Map

Here is a simple example of displaying a map with controls.

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

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

In this example:

Map creates the interactive map.
center defines the initial geographical coordinates.
zoom controls the initial zoom level.
MapControls adds interactive map controls.
h-[320px] gives the map container a defined height.

The coordinates in this example point to New York City. You can replace them with the longitude and latitude of your preferred location.

Important: The map fills its parent container. Always provide a height to the parent element. Otherwise, the map may not appear correctly.

Step 5: Explore More Map Components

Once your first map works, you can explore additional components to build more advanced interfaces.

Some available components include:

MapMarker for displaying locations.
MarkerPopup for showing information when interacting with markers.
MarkerTooltip for displaying short descriptions.
MapRoute for drawing routes.
MapGeoJSON for displaying geographical datasets.
MapClusterLayer for grouping map markers.
MapArc for displaying connections between locations.

You can find examples and implementation details in the official mapcn documentation.

What Can You Build With mapcn?

mapcn can be useful in different types of React applications.

Here are some practical examples.

1. Travel and Tourism Applications

Display tourist destinations, hotels, restaurants, and attractions on an interactive map. Users can explore different locations and view additional information through markers and popups.

2. Delivery Tracking Platforms

Use map markers and route components to visualize delivery locations and paths between destinations.

3. Store Locator Websites

Businesses can display their branches, shops, and service locations on an interactive map.

4. Analytics Dashboards

Developers can visualize geographical datasets, regional information, and location-based statistics using map layers and GeoJSON.

5. Logistics and Transportation Platforms

Map components can help display connections between locations, delivery routes, and transportation networks.

Is mapcn Free and Open Source?

Yes. mapcn is released under the MIT License.

The source code is publicly available on GitHub, allowing developers to use, modify, and contribute to the project under the license terms.

However, there is one important distinction regarding map tiles.

mapcn uses CARTO basemaps by default, powered by OpenStreetMap data. CARTO has separate usage limits, attribution requirements, and terms for its basemap services.

The project's current README describes free monthly usage allowances of up to 1 million tile requests for commercial use and 5 million for non-commercial use, subject to CARTO's terms.

If you plan to deploy a production application, review the CARTO terms and configure an appropriate basemap provider when necessary.

mapcn also supports other MapLibre-compatible providers, including MapTiler, Stadia Maps, and OpenStreetMap-based options.

The MIT license for mapcn does not automatically grant unrestricted usage rights for third-party map tiles.

Final Thoughts

mapcn is a useful project for developers who want to add interactive maps to React applications without building every map component from scratch.

Its integration with Tailwind CSS and shadcn/ui makes it particularly relevant to developers already using that ecosystem. The copy-and-customize approach also gives developers control over the components they install.

Whether you are building a travel website, delivery dashboard, store locator, or geographical data visualization, mapcn provides components worth exploring.

If you work with React or Next.js, you can explore the project and try it in your next application.

Project Links:

mapcn Guide: Install Interactive Map Components in React