CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-pigeon-maps

ReactJS maps without external dependencies - performance-first React-centric extendable map engine

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview
Eval results
Files

providers.mddocs/

Tile Providers

Built-in tile provider functions for popular map services with customization options and high-DPI support. Providers generate tile URLs for different map services and styles, enabling custom map appearances without external dependencies.

Capabilities

OpenStreetMap Provider

Default tile provider using OpenStreetMap tiles.

/**
 * OpenStreetMap tile provider (default)
 * @param x - Tile X coordinate
 * @param y - Tile Y coordinate  
 * @param z - Zoom level
 * @returns Tile URL string
 */
function osm(x: number, y: number, z: number): string;

Usage Example:

import React from "react";
import { Map } from "pigeon-maps";
import { osm } from "pigeon-maps/providers";

function OSMMap() {
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={osm}
    />
  );
}

Stamen Toner Provider

High-contrast black and white map style from Stamen Design.

/**
 * Stamen Toner tile provider with high-DPI support
 * @param x - Tile X coordinate
 * @param y - Tile Y coordinate
 * @param z - Zoom level
 * @param dpr - Device pixel ratio (optional, defaults to 1)
 * @returns Tile URL string with appropriate resolution
 */
function stamenToner(x: number, y: number, z: number, dpr?: number): string;

Usage Example:

import React from "react";
import { Map } from "pigeon-maps";
import { stamenToner } from "pigeon-maps/providers";

function TonerMap() {
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={stamenToner}
      dprs={[1, 2]} // Enable high-DPI tiles
    />
  );
}

Stamen Terrain Provider

Terrain map style with elevation shading from Stamen Design.

/**
 * Stamen Terrain tile provider with high-DPI support
 * @param x - Tile X coordinate
 * @param y - Tile Y coordinate
 * @param z - Zoom level
 * @param dpr - Device pixel ratio (optional, defaults to 1)
 * @returns Tile URL string with appropriate resolution
 */
function stamenTerrain(x: number, y: number, z: number, dpr?: number): string;

Usage Example:

import React from "react";
import { Map } from "pigeon-maps";
import { stamenTerrain } from "pigeon-maps/providers";

function TerrainMap() {
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={stamenTerrain}
      dprs={[1, 2]} // Enable high-DPI tiles
    />
  );
}

MapTiler Provider

Configurable provider for MapTiler cloud service with multiple map styles.

/**
 * MapTiler provider factory function
 * @param apiKey - MapTiler API key
 * @param map - Map style identifier (optional, defaults to 'streets')
 * @returns Tile provider function with high-DPI support
 */
function maptiler(apiKey: string, map?: string): TileProvider;

type TileProvider = (x: number, y: number, z: number, dpr?: number) => string;

Available Map Styles:

  • 'streets' (default): Standard street map
  • 'satellite': Satellite imagery
  • 'hybrid': Satellite with street labels
  • 'terrain': Terrain visualization
  • 'topo': Topographic map

Usage Examples:

import React from "react";
import { Map } from "pigeon-maps";
import { maptiler } from "pigeon-maps/providers";

// Basic streets map
function MapTilerStreets() {
  const provider = maptiler('your-api-key');
  
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={provider}
      dprs={[1, 2]}
    />
  );
}

// Satellite imagery
function MapTilerSatellite() {
  const provider = maptiler('your-api-key', 'satellite');
  
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={provider}
      dprs={[1, 2]}
    />
  );
}

// Multiple styles with switcher
function MapTilerWithStyleSwitcher() {
  const [style, setStyle] = useState('streets');
  const provider = maptiler('your-api-key', style);
  
  return (
    <div>
      <div style={{ marginBottom: '10px' }}>
        <button onClick={() => setStyle('streets')}>Streets</button>
        <button onClick={() => setStyle('satellite')}>Satellite</button>
        <button onClick={() => setStyle('terrain')}>Terrain</button>
      </div>
      <Map 
        height={400} 
        center={[50.879, 4.6997]} 
        zoom={11}
        provider={provider}
        dprs={[1, 2]}
      />
    </div>
  );
}

Stadia Maps Provider

Configurable provider for Stadia Maps service with multiple styles.

/**
 * Stadia Maps provider factory function
 * @param style - Map style identifier (optional, defaults to 'alidade_smooth')
 * @returns Tile provider function with high-DPI support
 */
function stadiamaps(style?: string): TileProvider;

Available Styles:

  • 'alidade_smooth' (default): Clean, smooth street map
  • 'alidade_smooth_dark': Dark theme version
  • 'outdoors': Outdoor/hiking focused map
  • 'stamen_terrain': Terrain visualization
  • 'stamen_toner': High-contrast black and white
  • 'stamen_watercolor': Artistic watercolor style

Usage Examples:

import React from "react";
import { Map } from "pigeon-maps";
import { stadiamaps } from "pigeon-maps/providers";

// Default smooth style
function StadiaSmooth() {
  const provider = stadiamaps();
  
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={provider}
      dprs={[1, 2]}
    />
  );
}

// Dark theme
function StadiaDark() {
  const provider = stadiamaps('alidade_smooth_dark');
  
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={provider}
      dprs={[1, 2]}
    />
  );
}

// Outdoors style
function StadiaOutdoors() {
  const provider = stadiamaps('outdoors');
  
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={provider}
      dprs={[1, 2]}
    />
  );
}

Custom Providers

Creating Custom Providers

You can create custom tile providers by implementing the TileProvider interface:

type TileProvider = (x: number, y: number, z: number, dpr?: number) => string;

Custom Provider Examples:

// Simple custom provider
function customTileProvider(x, y, z) {
  return `https://mytileserver.com/${z}/${x}/${y}.png`;
}

// Provider with API key
function createCustomProvider(apiKey) {
  return (x, y, z, dpr = 1) => {
    const resolution = dpr >= 2 ? '@2x' : '';
    return `https://api.example.com/tiles/${z}/${x}/${y}${resolution}.png?key=${apiKey}`;
  };
}

// Provider with subdomain rotation
function createRotatingProvider(subdomains = ['a', 'b', 'c']) {
  return (x, y, z) => {
    const subdomain = subdomains[(x + y) % subdomains.length];
    return `https://${subdomain}.tiles.example.com/${z}/${x}/${y}.png`;
  };
}

// Usage
function CustomProviderMap() {
  const myProvider = createCustomProvider('my-api-key');
  
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={myProvider}
    />
  );
}

High-DPI Support

Device Pixel Ratio

Many providers support high-DPI displays through the dpr parameter:

// Standard resolution (dpr = 1)
provider(x, y, z, 1) // → "...tile.png"

// High resolution (dpr = 2)  
provider(x, y, z, 2) // → "...tile@2x.png"

Configuring High-DPI

import React from "react";
import { Map } from "pigeon-maps";
import { stamenToner } from "pigeon-maps/providers";

function HighDPIMap() {
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={stamenToner}
      dprs={[1, 2]} // Enable both standard and high-DPI tiles
    />
  );
}

Automatic Detection

The map automatically detects device pixel ratio and requests appropriate tiles when dprs array is provided.

Provider Switching

Dynamic Provider Switching

import React, { useState } from "react";
import { Map } from "pigeon-maps";
import { osm, stamenToner, stamenTerrain, maptiler } from "pigeon-maps/providers";

function ProviderSwitcher() {
  const [currentProvider, setCurrentProvider] = useState('osm');
  
  const providers = {
    osm: osm,
    toner: stamenToner,
    terrain: stamenTerrain,
    maptiler: maptiler('your-api-key')
  };
  
  return (
    <div>
      <div style={{ marginBottom: '10px' }}>
        {Object.keys(providers).map(key => (
          <button 
            key={key}
            onClick={() => setCurrentProvider(key)}
            style={{ 
              margin: '2px',
              backgroundColor: currentProvider === key ? '#007bff' : '#f8f9fa'
            }}
          >
            {key.toUpperCase()}
          </button>
        ))}
      </div>
      <Map 
        height={400} 
        center={[50.879, 4.6997]} 
        zoom={11}
        provider={providers[currentProvider]}
        dprs={[1, 2]}
      />
    </div>
  );
}

Attribution Requirements

Different tile providers have different attribution requirements:

OpenStreetMap

© OpenStreetMap contributors

Stamen Design

Map tiles by Stamen Design, under CC BY 3.0. Data by OpenStreetMap, under ODbL.

MapTiler

© MapTiler © OpenStreetMap contributors

Setting Attribution

import React from "react";
import { Map } from "pigeon-maps";
import { maptiler } from "pigeon-maps/providers";

function AttributedMap() {
  return (
    <Map 
      height={400} 
      center={[50.879, 4.6997]} 
      zoom={11}
      provider={maptiler('your-api-key')}
      attribution={
        <span>
          © <a href="https://www.maptiler.com/">MapTiler</a> © <a href="https://www.openstreetmap.org/copyright">OpenStreetMap</a> contributors
        </span>
      }
    />
  );
}

Performance Considerations

  • Tile providers with CDN support (like Stamen, MapTiler) typically load faster
  • High-DPI tiles are larger files but provide better quality on high-density displays
  • Consider caching policies of different tile services
  • Some providers have rate limits or require API keys
  • Subdomain rotation can improve parallel download performance

Install with Tessl CLI

npx tessl i tessl/npm-pigeon-maps

docs

controls.md

draggable.md

geojson.md

index.md

map.md

markers-overlays.md

providers.md

tile.json