React components for Leaflet maps.

npm install react-leaflet

React, ReactDOM and Leaflet are peer dependencies, if you haven't already installed them use:

npm install leaflet react react-dom react-leaflet

An UMD build is also available on npmcdn:

<script src="https://npmcdn.com/react-leaflet/dist/react-leaflet.min.js"></script>

The library is injected as window.ReactLeaflet.

If you are not familiar with Leaflet, make sure you read its quick start guide first. You will need to add its CSS to your page to render the components properly.

All components are React wrappers for Leaflet elements and layers, they need a map instance and therefore must be included in a top-level <Map> component.

Leaflet example

import L from 'leaflet';

const position = [51.505, -0.09];
const map = L.map('map').setView(position, 13);

L.tileLayer('http://{s}.tile.osm.org/{z}/{x}/{y}.png', {
  attribution: '&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
}).addTo(map);

L.marker(position).addTo(map)
  .bindPopup('A pretty CSS3 popup. <br> Easily customizable.');

React-Leaflet

import React from 'react';
import { render } from 'react-dom';
import { Map, Marker, Popup, TileLayer } from 'react-leaflet';

const position = [51.505, -0.09];
const map = (
  <Map center={position} zoom={13}>
    <TileLayer
      url='http://{s}.tile.osm.org/{z}/{x}/{y}.png'
      attribution='&copy; <a href="http://osm.org/copyright">OpenStreetMap</a> contributors'
    />
    <Marker position={position}>
      <Popup>
        <span>A pretty CSS3 popup.<br/>Easily customizable.</span>
      </Popup>
    </Marker>
  </Map>
);

render(map, document.getElementById('map-container'));

Note that the <Map> component creates its own <div> container for the map, it does not get attached to an existing node.

This library uses React components as an interface, but not the virtual DOM, as all the DOM manipulations are managed by Leaflet, so there are a few things to keep in mind when using it:

• Leaflet makes direct calls to the DOM when it is loaded, therefore this library is not compatible with server-side rendering.
• The components exposed are abstractions for Leaflet layers, not DOM elements. Some of them have properties that can be updated directly by calling the setters exposed by Leaflet while others should be completely replaced, by setting an unique value on their key property so that they are properly handled by React's algorithm.
• Not all layers are implemented and even less tested.

setIconDefaultImagePath(path: string): Setter for Leaflet.Icon.Default.imagePath, set to //cdnjs.cloudflare.com/ajax/libs/leaflet/0.7.7/images by default.

latLng: One of [number, number], {lat: number, lng: number} or {lat: number, lon: number}.

latLngList: An Array of LatLng.

bounds: An instance of Leaflet.LatLngBounds or a LatLngList.

controlPosition: One of topleft, topright, bottomleft or bottomright.

Leaflet exposes its own events, different from React. You can listen to them using React-Leaflet by adding a callback to a property prefixed by onLeaflet or simply on. Ex: <Map onLeafletMoveend={this.handleMoveend}>...</Map>.
Check Leaflet documentation for the events associated to each component.

The properties documented for each component are the ones aimed to be supported (tested and made dynamic when possible) by React-Leaflet.
All other properties are passed as the options argument to their corresponding Leaflet element and should work fine for static maps, it is however unlikely that they would updated if you change them afterwards.

You can directly access the Leaflet element created by a component using the getLeafletElement() method on this component. This leaflet element is usually created in componentWillMount(), except for the Map component where it can only be created after the <div> container is rendered.

These components are base classes used by other components. They can be extended to create custom components but should not be used directly.

Base class extending React.Component and handling events binding and unbind.
It exposes a getLeafletElement() method to access the Leaflet object created for the component.

Base class extending React.Component for controls.
It exposes a getLeafletElement() method to access the Leaflet object created for the control.

Base class extending MapComponent using the provided map prop to add its element and passing it down to its children.
It exposes the following methods:

• getClonedChildrenWithMap(object extra): object: returns the cloned children of the component, adding the map and the extra props provided to them.
• renderChildrenWithProps(object props): object: returns the cloned children of the component using getClonedChildrenWithMap(), wrapped in a <div> with display: none style.

Base class extending MapLayer with a render() method and handling a TitleLayer opacity and zIndex props.

Base class extending MapLayer with the following methods:

• getPathOptions(object props): object: filters the input props and return a new object of Path options properties.
• setStyle(object options = {}): void: alias to the Leaflet element setStyle().
• setStyleIfChanged(object fromProps, object toProps): void: extracts the Path options of the two arguments, and calls setStyle() with the new options if different from the previous ones.

This is the top-level component that must be mounted for children ones to be rendered. Refer to Leaflet documentation for more information about the properties.

Properties

• bounds: bounds (optional, dynamic): A rectangle for the map to contain. It will be centered, and the map will zoom in as close as it can while still showing the full bounds. This property is dynamic, if you change it it will be reflected on the map.
• boundsOptions: object (optional, dynamic): Options passed to the fitBounds() method.
• center: latLng (optional, dynamic): Center of the map. This property is dynamic, if you change it it will be reflected in the map.
• className: string (optional, dynamic): className property of the <div> container for the map.
• id: string (optional): The ID of the <div> container for the map. If you don't provide it, a unique one will be created.
• maxBounds: bounds (optional, dynamic)
• maxZoom: number (optional)
• minZoom: number (optional)
• style: object (optional, dynamic): style property of the <div> container for the map.
• zoom: number (optional, dynamic)

• position: latLng (required, dynamic)
• icon: Leaflet.Icon (optional, dynamic)
• zIndexOffset: number (optional, dynamic)
• opacity: number (optional, dynamic)

The Popup children will be rendered using ReactDOM.render(), they must be valid React elements.

• position: latLng (optional, dynamic)

• url: string (required, dynamic)
• opacity: number (optional, dynamic)
• zIndex: number (optional, dynamic)

• url: string (required, dynamic)
• opacity: number (optional, dynamic)
• attribution: string (optional)

• CanvasTileLayer
• WMSTileLayer

All vector layers extend the Path component and therefore accept dynamic Path options properties.

• center: latLng (required, dynamic)
• radius: number (required, dynamic)

• center: latLng (required, dynamic)
• radius: number (optional, dynamic)

• positions: latLngList (required, dynamic)

• polylines: array<latLngList> (required, dynamic)

• positions: latLngList | Array<latLngList> (required, dynamic)

• polygons: array<latLngList> (required, dynamic)

• bounds: bounds (required, dynamic)

Use the LayerGroup wrapper component to group children layers together.

Extended LayerGroup supporting a Popup child.

• data: GeoJSON (required)

• position: controlPosition (optional, dynamic)
• prefix: string (optional)

• imperial: bool (optional)
• position: controlPosition (optional, dynamic)
• maxWidth: number (optional)
• metric: bool (optional)
• updateWhenIdle: bool (optional)

• position: controlPosition (optional, dynamic)
• zoomInText: string (optional)
• zoomInTitle: string (optional)
• zoomOutText: string (optional)
• zoomOutTitle: string (optional)

If you want to create custom components, for example Leaflet plugins, you could extend one of the base components depending on the type of component you want to implement.
The created Leaflet map instance is injected by the Map component to all its children as the map property. Make sure to inject it in your component's children as well.

See CHANGELOG file.

MIT
See LICENSE file.