mapboxgl-comparison

A lightweight, high-performance comparison layer for Mapbox GL JS. Overlay and compare raster tile sources using WebGL shaders — without the overhead of multiple map instances.

Features

• Single map instance — No duplicate maps or data, just efficient shader-based rendering
• Dual-axis comparison — Control visibility via both X and Y offsets
• WebGL-powered — GPU-accelerated rendering for smooth performance
• TypeScript support — Full type definitions included
• Framework-agnostic — Works with vanilla JS, React, Vue, or any framework

Installation

npm install mapboxgl-comparison mapbox-gl

Requirements

• mapbox-gl: ^3.3.0 or higher
• Modern browser with WebGL support

Quick Start

import mapboxgl from "mapbox-gl";
import { ComparisonLayer } from "mapboxgl-comparison";

mapboxgl.accessToken = "YOUR_MAPBOX_TOKEN";

const map = new mapboxgl.Map({
  container: "map",
  style: "mapbox://styles/mapbox/streets-v12",
  center: [-74.5, 40],
  zoom: 9,
});

// Create the comparison layer
const comparisonLayer = new ComparisonLayer(
  "comparison-layer",      // Unique layer ID
  "overlay-source",        // Source ID for the overlay tiles
  {
    type: "raster",
    tiles: ["https://tile.waymarkedtrails.org/hiking/{z}/{x}/{y}.png"],
  },
  { offsetX: 0.5, offsetY: 0 }  // Initial position (0-1 range)
);

// Add to map
map.once("load", () => {
  map.addLayer(comparisonLayer);
});

// Update position dynamically
comparisonLayer.updateData({ offsetX: 0.7, offsetY: 0 });

API Reference

ComparisonLayer

A custom Mapbox GL JS layer for comparing raster tile sources.

Constructor

new ComparisonLayer(
  id: string,              // Unique layer identifier
  sourceId: string,        // Source ID for overlay tiles
  tileJson: RasterSource,  // Mapbox raster source specification
  data: {                  // Initial offset configuration
    offsetX: number;       // Horizontal offset (0-1)
    offsetY: number;       // Vertical offset (0-1)
  }
)

Methods

| Method | Description | |--------|-------------| | updateData(data) | Updates the offset values and triggers a repaint | | onRemove() | Cleans up resources when layer is removed |

Properties

| Property | Type | Description | |----------|------|-------------| | id | string | Layer identifier | | sourceId | string | Overlay source identifier | | type | "custom" | Mapbox layer type |

How It Works

Unlike mapbox-gl-compare, which creates two separate map instances, this library uses a single map with a custom WebGL layer. The overlay raster tiles are rendered via fragment shaders, with visibility controlled by offsetX and offsetY uniforms.

This approach offers:

• Lower memory usage — One map instance instead of two
• Better performance — No synchronization overhead between maps
• Simpler API — Just update offset values to control visibility

Use Cases

• Compare historical vs. current imagery
• Overlay sensor data on base maps
• Visualize before/after scenarios
• Display alternative routing options

Browser Support

Requires WebGL support. Compatible with all modern browsers:

• Chrome 60+
• Firefox 55+
• Safari 11+
• Edge 79+

License

MIT © Vinicius Carra

Acknowledgments

Inspired by Stamen's work on raster map shaders.