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

Supports all commonly used projections
Extends Leaflet with full TMS support even for local projections
Makes it easy to use GeoJSON data with other projections than WGS84
Image overlays with bounds set from projected coordinates rather than LatLngs

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.

OSM tiling schema example - the example shown above, with EPSG:3006 with tiles using OpenStreetMap's tiling scheme
TMS tiling schema example using EPSG:5181 with tiles using TMS tiling scheme
WMS example using EPSG:3006 with tiles from a WMS service
WMTS example using EPSG:3006 with tiles from WMTS service
GeoJSON example displaying a GeoJSON with coordinates in EPSG:26915 on a Leaflet map with spherical mercator projection