or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

configuration.mdcontrols.mdevents.mdgeographic-utilities.mdindex.mdmap-core.mdui-components.md
tile.json

tessl/npm-mapbox-gl

A WebGL interactive maps library for creating customizable vector maps on the web

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/mapbox-gl@3.14.x

To install, run

npx @tessl/cli install tessl/npm-mapbox-gl@3.14.0

index.mddocs/

Mapbox GL JS

Mapbox GL JS is a comprehensive JavaScript library for creating interactive, customizable vector maps on the web using WebGL rendering. It processes map styles conforming to the Mapbox Style Specification and applies them to vector tiles following the Mapbox Vector Tile Specification to deliver high-performance, visually rich mapping experiences.

Package Information

  • Package Name: mapbox-gl
  • Package Type: npm
  • Language: TypeScript/JavaScript
  • Installation: npm install mapbox-gl
  • CSS: Requires import 'mapbox-gl/dist/mapbox-gl.css' or link to stylesheet

Core Imports

ESM (preferred):

import mapboxgl from 'mapbox-gl';

For specific components:

import { Map, Marker, Popup, NavigationControl } from 'mapbox-gl';

CommonJS:

const mapboxgl = require('mapbox-gl');

Basic Usage

import mapboxgl from 'mapbox-gl';

// Set access token
mapboxgl.accessToken = 'pk.your_access_token_here';

// Create map
const map = new mapboxgl.Map({
  container: 'map', // container ID
  style: 'mapbox://styles/mapbox/streets-v12',
  center: [-74.006, 40.7128], // [lng, lat]
  zoom: 9
});

// Add marker
const marker = new mapboxgl.Marker()
  .setLngLat([-74.006, 40.7128])
  .addTo(map);

// Add popup
const popup = new mapboxgl.Popup()
  .setLngLat([-74.006, 40.7128])
  .setHTML('<h3>Hello World!</h3>')
  .addTo(map);

Architecture

Mapbox GL JS is built around several key components:

  • Map Class: Core map management, rendering, and interaction handling
  • Style System: Complete Mapbox Style Specification implementation for visual styling
  • Source Management: Data source handling (vector, raster, GeoJSON, image, video)
  • Layer System: Rendering layers with data-driven styling and expressions
  • Geographic Utilities: Coordinate systems, projections, and spatial calculations
  • UI Components: Markers, popups, and interactive overlays
  • Control System: Pluggable UI controls (navigation, geolocation, attribution, etc.)
  • Event System: Comprehensive event handling for user interactions and map state changes
  • WebGL Rendering: Hardware-accelerated rendering with 3D terrain and lighting support

Capabilities

Map and Core Functionality

Central map creation, styling, data management, and rendering capabilities. The Map class is the primary interface for all mapping operations.

class Map extends Camera {
  constructor(options: MapOptions);
  
  // Style and data management
  addSource(id: string, source: SourceSpecification): Map;
  addLayer(layer: LayerSpecification, beforeId?: string): Map;
  setStyle(style: StyleSpecification | string, options?: StyleSetterOptions): Map;
  
  // Feature querying
  queryRenderedFeatures(geometry?: PointLike | [PointLike, PointLike], options?: QueryRenderedFeaturesParams): MapboxGeoJSONFeature[];
  
  // Control management
  addControl(control: IControl, position?: ControlPosition): Map;
}

interface MapOptions {
  container: string | HTMLElement;
  style?: StyleSpecification | string;
  center?: LngLatLike;
  zoom?: number;
  bearing?: number;
  pitch?: number;
  // ... additional options
}

Map and Core

UI Components

Interactive overlay components including markers and popups for displaying information and providing user interaction points.

class Marker extends Evented {
  constructor(options?: MarkerOptions);
  addTo(map: Map): Marker;
  setLngLat(lnglat: LngLatLike): Marker;
  setPopup(popup?: Popup): Marker;
}

class Popup extends Evented {
  constructor(options?: PopupOptions);
  addTo(map: Map): Popup;
  setLngLat(lnglat: LngLatLike): Popup;
  setHTML(html: string): Popup;
}

UI Components

Controls

Built-in UI controls for common map interactions including navigation, geolocation, and attribution display.

class NavigationControl implements IControl {
  constructor(options?: NavigationControlOptions);
  onAdd(map: Map): HTMLElement;
  onRemove(): void;
}

class GeolocateControl implements IControl {
  constructor(options?: GeolocateControlOptions);
  trigger(): boolean;
}

Controls

Geographic Utilities

Coordinate systems, geographic calculations, and spatial utility functions for working with map data and coordinates.

class LngLat {
  constructor(lng: number, lat: number);
  static convert(input: LngLatLike): LngLat;
  wrap(): LngLat;
  distanceTo(lnglat: LngLat): number;
}

class LngLatBounds {
  constructor(sw?: LngLatLike, ne?: LngLatLike);
  extend(obj: LngLatLike | LngLatBoundsLike): LngLatBounds;
  contains(lnglat: LngLatLike): boolean;
}

Geographic Utilities

Events and Interactions

Comprehensive event system for handling user interactions, map state changes, and data loading events.

interface MapMouseEvent {
  type: string;
  target: Map;
  originalEvent: MouseEvent;
  point: Point;
  lngLat: LngLat;
}

class Evented {
  on(type: string, listener: Function): this;
  off(type?: string, listener?: Function): this;
  once(type: string, listener: Function): this;
  fire(type: string, data?: any): this;
}

Events and Interactions

Configuration and Global Settings

Global configuration properties and utility functions for library-wide settings and resource management.

// Global properties (get/set)
declare const mapboxgl: {
  accessToken: string;
  baseApiUrl: string;
  workerCount: number;
  version: string;
  
  // Utility functions
  supported(options?: {failIfMajorPerformanceCaveat?: boolean}): boolean;
  prewarm(): void;
  clearPrewarmedResources(): void;
  setRTLTextPlugin(pluginURL: string, callback?: Function, lazy?: boolean): void;
};

Configuration and Global Settings

Style Class

Direct style manipulation and advanced style management capabilities beyond the Map class methods.

class Style extends Evented {
  constructor(styleSpec: StyleSpecification);
  
  // Core style operations
  addSource(id: string, source: SourceSpecification): void;
  removeSource(id: string): void;
  addLayer(layer: LayerSpecification, beforeId?: string): void;
  removeLayer(id: string): void;
  moveLayer(id: string, beforeId?: string): void;
  
  // Style state
  loaded(): boolean;
  serialize(): StyleSpecification;
}

Evented Base Class

Base event handling class that provides event management functionality for Map, Marker, Popup, and other components.

class Evented {
  /**
   * Adds an event listener
   * @param type - Event type
   * @param listener - Event handler function
   * @returns This object for chaining
   */
  on(type: string, listener: Function): this;
  
  /**
   * Removes an event listener
   * @param type - Event type (optional)
   * @param listener - Event handler function (optional)
   * @returns This object for chaining
   */
  off(type?: string, listener?: Function): this;
  
  /**
   * Adds a one-time event listener
   * @param type - Event type
   * @param listener - Event handler function
   * @returns This object for chaining
   */
  once(type: string, listener: Function): this;
  
  /**
   * Fires an event
   * @param type - Event type
   * @param data - Event data
   * @returns This object for chaining
   */
  fire(type: string, data?: any): this;
}

Common Types

// Geographic coordinate types
type LngLatLike = LngLat | [number, number] | { lng: number; lat: number } | { lon: number; lat: number };
type LngLatBoundsLike = LngLatBounds | [LngLatLike, LngLatLike] | [number, number, number, number];

// Screen coordinate types
type PointLike = Point | [number, number];

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

// Anchor positioning for popups and markers
type Anchor = 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';

// Event handling
interface Event {
  type: string;
  target: any;
  originalEvent?: any;
}

interface ErrorEvent extends Event {
  error: Error;
}

// Advanced 3D camera positioning
interface FreeCameraOptions {
  position?: MercatorCoordinate;
  orientation?: [number, number, number, number]; // quaternion [x, y, z, w]
}

// Style specifications for advanced features
interface TerrainSpecification {
  source: string;
  exaggeration?: number | ExpressionSpecification;
}

interface FogSpecification {
  range?: [number, number] | ExpressionSpecification;
  color?: ColorSpecification;
  'horizon-blend'?: number | ExpressionSpecification;
}

interface LightsSpecification {
  id?: string;
  type: 'ambient' | 'directional';
  properties?: {
    color?: ColorSpecification;
    intensity?: number | ExpressionSpecification;
    direction?: [number, number] | ExpressionSpecification;
  };
}

interface SnowSpecification {
  intensity?: number | ExpressionSpecification;
  accumulation?: number | ExpressionSpecification;
  opacity?: number | ExpressionSpecification;
}

interface RainSpecification {
  intensity?: number | ExpressionSpecification;
  opacity?: number | ExpressionSpecification;
}

// Configuration specifications
interface ConfigSpecification {
  [key: string]: any;
}

interface ImportSpecification {
  id: string;
  url?: string;
  data?: StyleSpecification;
  config?: ConfigSpecification;
}