maplibre-xy
v1.0.1
Published
Handy functions for flat, single-copy maps in maplibre-gl-js. Includes a parameterized underzoom transformConstrain.
Maintainers
larsmaxfieldReadme
maplibre-xy
Handy functions for maplibre-gl-js to improve flat single-copy maps, 'simple' maps, and non-maps like high-resolution images.
Install with NPM:
npm install maplibre-xyOr import modules as needed to your script from unpkg or locally from the repo's /src:
import { Underzoom } from 'https://unpkg.com/maplibre-xy';
// or
import { Underzoom } from './src/index.js';Features with code examples:
- Underzoom: Zoom and pan the map to show the entire bounded area - HTML example
Install
You can access the modules in a couple ways.
NPM
npm install maplibre-xyimport { Underzoom } from 'maplibre-xy'unpkg
import { Underzoom } from 'https://unpkg.com/maplibre-xy';Source
You can also clone the repo or simply copy the /src folder contents:
import { Underzoom } from './src/index.js';Or just copy individual modules (like/src/underzoom.js) if you need just need those.
Features
Underzoom
Let users see the entire bounded area within defined limits by passing Underzoom.transformConstrain to the Map constructor's transformConstrain option:
import { Underzoom } from 'maplibre-xy'; // NPM
// or
import { Underzoom } from 'https://unpkg.com/maplibre-xy'; // unpkg
const myUnderzoom = new Underzoom(maplibregl); // Uses default limits
const map = new maplibregl.Map({
transformConstrain: myUnderzoom.transformConstrain,
...This is especially useful for responsibly showing the whole map when renderWorldCopies=false.
Customize
You can modify the limits by passing an options object. The underzoom demo lets you preview the effect of each limit 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);HTML example
<!DOCTYPE html>
<html lang='en'>
<head>
<title>Underzoom minimal example</title>
<meta property='og:description' content='Underzoom minimal example' />
<meta charset='utf-8'>
<meta name='viewport' content='width=device-width, initial-scale=1'>
<link rel='stylesheet' href='https://unpkg.com/[email protected]/dist/maplibre-gl.css' />
<script src='https://unpkg.com/[email protected]/dist/maplibre-gl.js'></script>
<style>
body {
margin: 0;
padding: 0;
}
html, body, #map { height: 100%; }
</style>
</head>
<body>
<div id='map'></div>
<script type="module">
import { Underzoom } from 'https://unpkg.com/maplibre-xy';
const myUnderzoom = new Underzoom(maplibregl, { extendScale: 0.5, extendPan: 1.0 });
const map = new maplibregl.Map({
container: 'map',
renderWorldCopies: false,
transformConstrain: myUnderzoom.transformConstrain,
style: {
version: 8,
sources: {
rgb: {
type: 'raster',
tiles: ['https://a.tile.openstreetmap.org/{z}/{x}/{y}.png'],
tileSize: 256,
attribution: '© OpenStreetMap Contributors',
maxzoom: 19
},
},
layers: [
{
id: 'rgb',
type: 'raster',
source: 'rgb'
},
]
},
});
</script>
</body>
</html>Contributing
Feature requests, bug reports, and pull requests are always welcome.