or run

npx @tessl/cli init

Version

Tile

Overview

Evals

Files

docs

events-types.md index.md mapbox-legacy.md mapbox-maplibre.md

tile.json

tessl/npm-react-map-gl

React components for MapLibre GL JS and Mapbox GL JS that provide a React-friendly API wrapper for interactive mapping applications

Workspace: tessl
Visibility: Public
Created: 3 months ago
Last updated: 3 months ago
Describes: pkg:npm/react-map-gl@8.0.x

To install, run

npx @tessl/cli install tessl/npm-react-map-gl@8.0.0

React Map GL

React Map GL provides React components for MapLibre GL JS and Mapbox GL JS, offering a React-friendly API wrapper for interactive mapping applications. The library enables developers to integrate performant, customizable maps into React applications with declarative components, hooks, and comprehensive TypeScript support.

Package Information

Package Name: react-map-gl
Package Type: npm
Language: TypeScript
Installation: npm install react-map-gl

Core Imports

React Map GL provides three different import paths for different mapping backends:

For Mapbox GL JS:

import Map, { 
  Marker, 
  Popup, 
  NavigationControl, 
  Source, 
  Layer, 
  useMap, 
  MapProvider 
} from "react-map-gl/mapbox";

For MapLibre GL JS:

import Map, { 
  Marker, 
  Popup, 
  NavigationControl, 
  Source, 
  Layer, 
  useMap, 
  MapProvider,
  TerrainControl,
  LogoControl 
} from "react-map-gl/maplibre";

For Legacy Mapbox (backwards compatibility):

import Map, { 
  Marker, 
  Popup, 
  NavigationControl, 
  Source, 
  Layer, 
  useMap, 
  MapProvider 
} from "react-map-gl/mapbox-legacy";

CommonJS:

const { 
  Map, 
  Marker, 
  Popup, 
  NavigationControl, 
  Source, 
  Layer, 
  useMap, 
  MapProvider 
} = require("react-map-gl/mapbox");

Basic Usage

import React from 'react';
import Map, { Marker, Popup, NavigationControl } from 'react-map-gl/mapbox';
import 'mapbox-gl/dist/mapbox-gl.css';

function MyMap() {
  const [viewState, setViewState] = React.useState({
    longitude: -100,
    latitude: 40,
    zoom: 3.5,
    bearing: 0,
    pitch: 0,
    padding: { top: 0, bottom: 0, left: 0, right: 0 }
  });

  return (
    <Map
      {...viewState}
      onMove={evt => setViewState(evt.viewState)}
      style={{width: 600, height: 400}}
      mapStyle="mapbox://styles/mapbox/streets-v9"
      mapboxAccessToken="YOUR_MAPBOX_TOKEN"
    >
      <Marker longitude={-100} latitude={40} color="red" />
      <NavigationControl position="top-right" />
    </Map>
  );
}

Architecture

React Map GL is built around several key architectural patterns:

Multiple Backend Support: Three export paths supporting Mapbox GL, MapLibre GL, and legacy Mapbox implementations
Declarative Components: Map, markers, popups, controls, sources, and layers as React components
Hooks Integration: Custom hooks for map access, control management, and state handling
Type Safety: Full TypeScript definitions with generic type preservation
Event System: Comprehensive event handling for map interactions, view changes, and user interactions
Ref Pattern: Imperative map access through React refs for advanced use cases

Capabilities

Core Map Component

The main Map component providing the foundation for interactive mapping applications. Supports both controlled and uncontrolled patterns with comprehensive event handling.

interface MapProps extends MapInitOptions, MapboxProps, GlobalSettings {
  mapLib?: MapLib | Promise<MapLib>;
  reuseMaps?: boolean;
  id?: string;
  style?: CSSProperties;
  children?: any;
}

interface MapRef {
  getMap(): MapInstance;
}

function Map(props: MapProps): JSX.Element;

UI Components

Interactive map elements including markers, popups, and map controls for building rich mapping experiences.

interface MarkerProps {
  longitude: number;
  latitude: number;
  anchor?: string;
  offset?: PointLike;
  color?: string;
  scale?: number;
  draggable?: boolean;
  rotation?: number;
  rotationAlignment?: string;
  pitchAlignment?: string;
  onClick?: (event: MarkerEvent) => void;
  onDragStart?: (event: MarkerDragEvent) => void;
  onDrag?: (event: MarkerDragEvent) => void;
  onDragEnd?: (event: MarkerDragEvent) => void;
  style?: CSSProperties;
  className?: string;
  children?: any;
}

function Marker(props: MarkerProps): JSX.Element;

interface PopupProps {
  longitude: number;
  latitude: number;
  anchor?: string;
  offset?: PointLike;
  maxWidth?: string;
  className?: string;
  style?: CSSProperties;
  closeButton?: boolean;
  closeOnClick?: boolean;
  closeOnMove?: boolean;
  focusAfterOpen?: boolean;
  onClose?: () => void;
  children?: any;
}

function Popup(props: PopupProps): JSX.Element;

Mapbox and MapLibre Components

Data Sources and Layers

Components for managing map data sources and rendering layers, enabling custom data visualization and styling.

interface SourceProps extends SourceSpecification {
  id?: string;
  children?: React.ReactNode;
}

function Source(props: SourceProps): JSX.Element;

interface LayerProps extends LayerSpecification {
  id?: string;
  beforeId?: string;
}

function Layer(props: LayerProps): JSX.Element;

Map Controls

Interactive controls for map navigation, geolocation, attribution, and other map functions.

interface NavigationControlProps {
  position?: ControlPosition;
  showCompass?: boolean;
  showZoom?: boolean;
  visualizePitch?: boolean;
}

function NavigationControl(props: NavigationControlProps): JSX.Element;

interface GeolocateControlProps {
  position?: ControlPosition;
  positionOptions?: PositionOptions;
  fitBoundsOptions?: FitBoundsOptions;
  trackUserLocation?: boolean;
  showAccuracyCircle?: boolean;
  showUserLocation?: boolean;
}

function GeolocateControl(props: GeolocateControlProps): JSX.Element;

interface AttributionControlProps {
  position?: ControlPosition;
  compact?: boolean;
  customAttribution?: string | string[];
}

function AttributionControl(props: AttributionControlProps): JSX.Element;

interface FullscreenControlProps {
  position?: ControlPosition;
  container?: HTMLElement;
}

function FullscreenControl(props: FullscreenControlProps): JSX.Element;

interface ScaleControlProps {
  position?: ControlPosition;
  maxWidth?: number;
  unit?: 'imperial' | 'metric' | 'nautical';
}

function ScaleControl(props: ScaleControlProps): JSX.Element;

Hooks and Context

React hooks and context providers for accessing map instances and creating custom controls.

function useMap(): MapRef;

function useControl<T extends IControl>(
  onCreate: (map: MapInstance) => T,
  onRemove?: (control: T) => void,
  options?: { position?: ControlPosition }
): T;

interface MapProviderProps {
  children: React.ReactNode;
}

function MapProvider(props: MapProviderProps): JSX.Element;

Legacy Implementation

Backward-compatible implementation for applications using older Mapbox GL versions and patterns.

// Same component interfaces as modern implementation
// but with legacy internal behavior and compatibility

Legacy Mapbox Components

Event System and Types

Comprehensive event handling system with strongly-typed event objects for all map interactions.

interface ViewState {
  longitude: number;
  latitude: number;
  zoom: number;
  bearing: number;
  pitch: number;
  padding: PaddingOptions;
}

interface ViewStateChangeEvent {
  viewState: ViewState;
  interactionState: InteractionState;
  originalEvent: Event;
}

interface InteractionState {
  inTransition: boolean;
  isDragging: boolean;
  isPanning: boolean;
  isRotating: boolean;
  isZooming: boolean;
}

interface MapCallbacks {
  onMove?: (event: ViewStateChangeEvent) => void;
  onMoveStart?: (event: ViewStateChangeEvent) => void;
  onMoveEnd?: (event: ViewStateChangeEvent) => void;
  onClick?: (event: MapMouseEvent) => void;
  onDblClick?: (event: MapMouseEvent) => void;
  onMouseDown?: (event: MapMouseEvent) => void;
  onMouseUp?: (event: MapMouseEvent) => void;
  onMouseOver?: (event: MapMouseEvent) => void;
  onMouseMove?: (event: MapMouseEvent) => void;
  onMouseOut?: (event: MapMouseEvent) => void;
  onContextMenu?: (event: MapMouseEvent) => void;
  onWheel?: (event: MapWheelEvent) => void;
  onTouchStart?: (event: MapTouchEvent) => void;
  onTouchEnd?: (event: MapTouchEvent) => void;
  onTouchMove?: (event: MapTouchEvent) => void;
  onTouchCancel?: (event: MapTouchEvent) => void;
}

Events and Types

Key Types

// Geometric types
type Point = {
  x: number;
  y: number;
};

type PointLike = Point | [number, number];

type LngLat = {
  lng: number;
  lat: number;
};

type LngLatLike = LngLat | [number, number] | {lon: number; lat: number};

type LngLatBounds = {
  _sw: LngLat;
  _ne: LngLat;
};

type LngLatBoundsLike = 
  | LngLatBounds 
  | [LngLatLike, LngLatLike] 
  | [number, number, number, number];

type PaddingOptions = {
  top?: number;
  bottom?: number;
  left?: number;
  right?: number;
};

// Control positioning
type ControlPosition = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

// Source types
interface SourceSpecification {
  type: 'vector' | 'raster' | 'raster-dem' | 'geojson' | 'image' | 'video' | 'canvas';
  url?: string;
  tiles?: string[];
  bounds?: [number, number, number, number];
  scheme?: 'xyz' | 'tms';
  minzoom?: number;
  maxzoom?: number;
  attribution?: string;
  data?: any;
  coordinates?: [[number, number], [number, number], [number, number], [number, number]];
  canvas?: string | HTMLCanvasElement;
}

// Layer types
interface LayerSpecification {
  id: string;
  type: 'fill' | 'line' | 'symbol' | 'circle' | 'heatmap' | 'fill-extrusion' | 'raster' | 'hillshade' | 'background' | 'sky' | 'custom';
  source?: string;
  'source-layer'?: string;
  minzoom?: number;
  maxzoom?: number;
  filter?: any[];
  layout?: Record<string, any>;
  paint?: Record<string, any>;
}

// Map instance types
interface MapLib {
  Map: any;
  Marker: any;
  Popup: any;
  AttributionControl: any;
  FullscreenControl: any;
  GeolocateControl: any;
  NavigationControl: any;
  ScaleControl: any;
}

interface MapInstance extends MapLib.Map {
  // Extended with library-specific methods
}

// Control interface
interface IControl {
  onAdd(map: MapInstance): HTMLElement;
  onRemove(map: MapInstance): void;
}

// Geolocation types
interface PositionOptions {
  enableHighAccuracy?: boolean;
  timeout?: number;
  maximumAge?: number;
}

interface FitBoundsOptions {
  padding?: number | PaddingOptions;
  linear?: boolean;
  easing?: (t: number) => number;
  around?: LngLatLike;
  maxZoom?: number;
  duration?: number;
}

// Context and hooks
interface MountedMapsContext {
  onMapMount: (map: MapRef, mapId: string) => void;
  onMapUnmount: (mapId: string) => void;
  maps: Record<string, MapRef>;
}