Bhaskar Karambelkar's Blog

Leaflet Diary: Chapter 2, Projections and then some


Tags: r r-stats rstats GIS leaflet Leaflet-Diary

This is the third blog entry in my series ‘Leaflet-Diary’. In my last post Chapter 1: Plugins galore, I talked about upgrading existing plugins and adding any missing functionality to those plugins. This one is about phase II, where I’ve added two extremely powerful features, custom projection support and custom buttons/toolbars and also upgraded Leaflet JS to 0.7.7.


  • Leaflet Javascript has been upgraded from 0.7.3 to 0.7.7, which is the latest release on the 0.7.x branch.
  • Support for adding custom buttons/toolbars using the Leaflet.EasyButton plugin.
  • Support for custom projections using Proj4Leaflet plugin.

You can try out the new stuff today by building the Leaflet package from source using devtools::install_github('rstudio/leaflet'). For a full list of changes see the pull request #298. Also the examples folder has lots of new examples. You can see working sample code at my Rpubs page.

Long Read

Leaflet 0.7.7

The Leaflet Javascript included with the package was ver. 0.7.3 released on May, 23rd 2014. A lot has happened since then. The 0.7 branch latest version is now 0.7.7, and now leaflet js is at ver 1.0.1.

Leaflet 1.x is a major version upgrade, which has some backward compatibility issues with 0.7.x branch. So instead of jumping straight to 1.x I decided to first upgrade to 0.7.7. This ensures compatibility with existing code but yet gives us all the benefits of the latest release. The 0.7.7 upgrade was part of commit 3f4720a, and while I was at it I also upgraded jQuery from 1.11.1 to 1.12.4.

Custom Buttons and Toolbars

There are quite a few plugins listed on the leaflet site for user interface add-ons. So it was a bit intimidating deciding which plugin to adopt for allowing users to define some custom buttons/toolbars. Finally I settled on the Leaflet.EasyButton plugin as it allows maximum flexibility in terms of adding your own buttons and toolbars and defining your own actions for them.

To give a small example, here is a code that allows you to reset the map view to [0, 0, 0].

leaflet() %>% addTiles() %>%
        icon = 'ion-arrow-shrink',
        title = 'Reset View',
        onClick = JS("
            function(btn, map){ map.setView([0,0],0); }")

There’s a lot more you can do with the EasyButtons plugins, and you can check out more examples at my Rpubs: EasyButtons page.


I now come to one of the most important features added to the leaflet package, projections support. If you are unsure about what projections are, I suggest staring from the Wikipedia entry on the subject, and there is always the XKCD Comic.

The projections support comes courtesy of the Proj4Leaflet plugin which provides the glue between leaflet and Proj4JS. With this addition you can now specify custom projections in your leaflet maps. Adding projections support to the leaflet package was more of a technical challenge than anything else, but with help from Tim Salabim, Michael Summer, Kent Russel, and Rstudio’s very own Joe Cheng we finally had success. Once the technical aspect was sorted out the challenge was making the R API straightforward and as idiomatic as possible, here again Joe’s experience was very helpful. This was truly a team effort. I got a lot of feedback and pointers from the R and GIS community both on Twitter and Github as I was baking in support for projections, which allowed me to solidify the code quite a bit.

I have quite a few examples for using custom projections on my Rpubs pages.

Here’s a nice view of Antarctica in it’s native EPSG:3031 projection.

Projections are a somewhat advanced concept and most web mapping users will not really need them. You should be mostly fine with the default spherical mercator projection. Before using projections be sure to read this note where I have discussed some inner working of the projections support and some limitations.

End of Phase 2

This marks the end of Phase 2 in my leaflet development. In next phase I’ll show you how you can augment the leaflet package by developing your own plugins and some examples that I have been working on. If you like what you see or have comments/questions/critiques don’t hesitate to contact me via Twitter or open an issue over at Github. In the mean time happy mapping.