AnmolSaini16/mapcn
Mapcn
MapCN is a React component library that wraps MapLibre GL into declarative, composable building blocks for interactive maps. It provides a set of small, reusable components for rendering maps, placing markers, drawing routes, and clustering points, all managed through React hooks, context, and refs for state and lifecycle control.
The library distinguishes itself by offering a complete set of map features as individual React components that automatically adapt to light and dark themes. It includes components for interactive map rendering with zero configuration, marker placement with popups and drag support, route and arc drawing with click and hover events, and native point clustering for large datasets. Map controls for zoom, compass, geolocation, and fullscreen are also provided as themed components.
Beyond the core components, the library supports custom GeoJSON layers, high-performance marker layers on the WebGL canvas, and programmatic access to the map instance for building extended capabilities like real-time tracking or heatmaps. It also offers composable map UIs, custom tile provider support, and dynamic style switching.
The library is distributed as a TypeScript package and is designed to be used in React applications that need interactive, theme-aware maps without requiring API keys.
Features
- Interactive Map Renderers - Renders a full-featured interactive map using MapLibre GL with zero configuration and automatic theme switching.
- GeoJSON Renderers - Renders markers, routes, and clusters as GeoJSON layers on the WebGL canvas for high-performance visualization.
- Interactive GeoJSON Layers - Renders custom GeoJSON data as styled layers with fill and outline that respond to hover interactions.
- Geographic Route Drawing - Draws styled routes and curved arcs between coordinates on a MapLibre map with click and hover events.
- Geographic Point Clustering - Groups nearby points into clusters at low zoom levels and expands them as the user zooms in to handle large datasets.
- Map Point Clustering - Group close points into expandable clusters using native clustering, with configurable colors and sizes.
- React Map Components - Provides declarative React components that compose into interactive map interfaces using MapLibre GL.
- Marker Interaction - Places DOM-based markers on a map that display custom content, open popups on click, and show tooltips on hover.
- Markers with Popups - Place rich markers on a map that can display popups, tooltips, and labels when interacted with.
- Marker Placement - Position a marker at a given longitude and latitude, supporting click, hover, and drag interactions.
- Imperative-to-Declarative Bridges - Wraps the MapLibre GL imperative API into declarative React components with hooks for state management and lifecycle control.
- Map Instance Access Patterns - Accesses the underlying map instance via hooks or refs to call methods, listen to events, and build custom features.
- Imperative Map Ref Access - Accesses the underlying map instance through a ref to call methods and listen to events.
- Map Marker Tooltips - Display a floating content box when the user hovers over a marker, which auto-dismisses on hover out.
- Map Marker Managers - Places interactive markers with popups, tooltips, and drag functionality to display rich content on map coordinates.
- Map UI Frameworks - Assembles complex map interfaces from simple, reusable components that compose together.
- Themed Map Controls - Add zoom, compass, locate, and fullscreen controls that automatically adapt to light and dark mode.
- Zero-Configuration Map Renderers - Initialize a MapLibre GL map inside a component, automatically handling theme switching and providing context for child elements.
- Map Marker Popups - Opens popups containing images, ratings, and action buttons when a user clicks a marker on the map.
- Map Style Theme Switching - Switches between light and dark map styles automatically based on the user's theme preference.
- Imperative Map Access Hooks - Provides React hooks to access the map instance, listen to events, and call methods directly from child components.
- Geographic Route Visualization - Draws routes, paths, and curved arcs between coordinates with styled lines and support for click and hover events.
- Spatial Clustering - Uses MapLibre GL's built-in clustering algorithm to group nearby points into expandable clusters with configurable appearance.
- Extended Map Layer Capabilities - Supports custom GeoJSON layers, real-time tracking, geofencing, heatmaps, and other extended map capabilities.
- Extended Map Layer Capabilities - Extends the map with real-time tracking, geofencing, heatmaps, drawing tools, 3D buildings, animations, and custom data layers.
- Map Marker Layers - Renders hundreds or thousands of markers as GeoJSON layers on the WebGL canvas for high performance.
- Geographic Arc Drawing - Renders quadratic Bézier arcs between two coordinates on a map, supporting per-arc styling and hover interactions.
- Route Stop Markers - Places numbered markers along a drawn path to indicate stops or waypoints.
- Custom Tile Provider Support - Connects to any tile provider that is compatible with the map library, including OpenStreetMap, Carto, and MapTiler.
- Draggable Markers - Repositions markers on the map by dragging them and shows the updated coordinates in a popup.
- Map Compass Displays - Displays a compass rose that indicates the current map bearing and can be clicked to reset north.
- Browser Geolocation Detectors - Uses the browser's geolocation API to find and center the map on the user's current location.
- Windowed Fullscreen Toggles - Switches the map display between windowed and fullscreen view to maximize the visible area.
- Map Popups - Render a content popup attached to a marker on click or at a standalone coordinate on the map.
- Coordinate - Zooms the map to a specified geographic coordinate or bounding box with a smooth animated transition.
- Map Route Alternatives - Shows multiple route alternatives and lets users select one by fetching directions from a routing API.
