Fork me on GitHub

Proj4Leaflet

Full Projection and CRS support in Leaflet

About Getting Started Examples API Download

About

Proj4Leaflet makes it possible to use projections and CRS not built into Leaflet. All major projections are supported by using the popular and well-tested Proj4js library.

Features

Getting started

Proj4Leaflet now supports Leaflet 1.0

To use Proj4Leaflet, you need to include two new scripts: Proj4.js and proj4leaflet.js. Put the scripts after Leaflet has been loaded, like this:

[...]
<script src="https://unpkg.com/leaflet@1.0.3/dist/leaflet.js"></script>
<script src="proj4.js"></script>
<script src="proj4leaflet.js"></script>
[...]

If you're using Browserify, Webpack or similar, Proj4Leaflet is available on npm:

npm install --save proj4leaflet

For basic usage, you need to create a L.Proj.CRS to represent the projection and CRS you want to use. To do this, you need to provide a Proj4 definition of the projection. If you do not already have the definition, you can find most at sites like epsg.io or spatialreference.org.

Depending on the configuration of your tiles, you might also need additional options for the CRS. Most common is to defined an origin for the tiles (where tile (0,0) is located) and the scale or resolution to use for zoom levels.

An example:

// SWEREF99 TM (EPSG:3006) with map's pixel origin at SWEREF99 TM coordinate (0, 0)
var crs = new L.Proj.CRS('EPSG:3006',
  '+proj=utm +zone=33 +ellps=GRS80 +towgs84=0,0,0,0,0,0,0 +units=m +no_defs',
  {
    resolutions: [
      8192, 4096, 2048, 1024, 512, 256, 128
    ],
    origin: [0, 0]
  })

Finally, instantiate a map with the newly created CRS like this:

var map = new L.Map('map', {
    crs: crs
  });

L.tileLayer('http://api.geosition.com/tile/osm-bright-3006/{z}/{x}/{y}.png', {
  maxZoom: crs.options.resolutions.length,
  minZoom: 0,
  continuousWorld: true,
  attribution: 'Map data © <a href="http://www.openstreetmap.org/copyright">OpenStreetMap contributors</a>, Imagery © <a href="http://www.kartena.se/">Kartena</a>'
}).addTo(map);

Note the use of the option continuousWorld for the tile layer, which tells Leaflet that the tiles should not be wrapped the same way they should for its default projection.

An example of the result:

Tiling in projections other than spherical mercator (the projection used in Leaflet by default) is a complex topic, and standards are often lacking. To get a better grasp of the concepts involved, you might want to refer to The Hitchhiker's Guide To Tiles Maps.

Examples

A couple of small examples showing of different features of Proj4Leaflet. Fire up your browser's debugger to see the code used.

For detailed docs, check out the API.


Copyright © Proj4Leaflet Contributors, released under BSD 2 Clause License.