maplibre-xy

Utilities for maplibre-gl-js to improve flat single-copy maps and non-maps like high-resolution image tilesets.

Demo for Underzoom

Features

See the features preview on the homepage:

• Underzoom: View the entire bounded area regardless of viewport aspect ratio.

Install

With NPM:

npm install maplibre-xy

import { Underzoom } from 'maplibre-xy'

From the UNPKG content delivery network (CDN):

import { Underzoom } from 'https://unpkg.com/maplibre-xy';

From the repo source:

import { Underzoom } from './src/index.js';

Use

Underzoom

Let users zoom out to see the entire bounded area regardless of viewport aspect ratio.

Demo

Simply create an Underzoom instance and pass its transformConstrain to the Map constructor's transformConstrain option. The transform extends the allowable zoom and pan to customizable limits:

import { Underzoom } from 'maplibre-xy';  // NPM
// or
import { Underzoom } from 'https://unpkg.com/maplibre-xy';  // UNPKG

const myUnderzoom = new Underzoom(maplibregl);  // Use default limits

const map = new maplibregl.Map({
    transformConstrain: myUnderzoom.transformConstrain,
    ...

This is especially useful when renderWorldCopies=false if you want to show the whole map on both mobile (a tall viewport) and desktop (a wide viewport). MapLibre's default Mercator transform doesn't allow this.

Minimal HTML example

Customize

You can modify the Underzoom limits by passing an options object and/or setting its properties. The underzoom demo lets you preview the effect extending scale ane pan on various bounded areas:

const underzoomOptions = {
    // Ratio (0-1) of how you far youcan zoom out
    // the bounds relative to the viewport size.
    extendScale: 0.5,  // Default 0.9

    // Ratio (0-1) of how far you can pan beyond
    // the bounds relative to the distance between
    // viewport edge and center.
    extendPan: 1.0,  // Default 0.2

    // Whether to enable or revert to default
    // Mercator constrain.
    extend: true  // Default true
};

const myUnderzoom = new Underzoom(maplibregl, underzoomOptions);

myUnderzoom.extendScale = 1.0;
myUnderzoom.extendPan = 0.0;  
myUnderzoom.extend = false;

Contributing

Feature requests, bug reports, and pull requests are always welcome.