Skip to main content
Version: v5.x (next)

Installation

React prerequisites​

This documentation assumes you are already familiar with React and have a project setup. If it is not the case, you should read React's Quick Start documentation first.

Leaflet prerequisites​

This documentation assumes you are already familiar with Leaflet. React Leaflet does not replace Leaflet, it only provides bindings between React and Leaflet.

This documentation is not a replacement for Leaflet's documentation, it only focuses on aspects specific to React Leaflet.

Read this before going further

Before using React Leaflet, you must setup your project following Leaflet's Quick Start Guide.

Adding React Leaflet​

Using ESM imports​

React Leaflet exports ES Modules that can be imported by URL, notably from CDNs such as esm.sh:

import { MapContainer } from 'https://cdn.esm.sh/react-leaflet/MapContainer'
import { TileLayer } from 'https://cdn.esm.sh/react-leaflet/TileLayer'
import { useMap } from 'https://cdn.esm.sh/react-leaflet/hooks'

Or importing the full library at once:

import {
  MapContainer,
  TileLayer,
  useMap,
} from 'https://cdn.esm.sh/react-leaflet'

Using a package registry​

A package registry such as npm can be used to install React Leaflet and its dependencies.

React, React DOM and Leaflet are required peer dependencies. You must add them to your project if they are not already installed:

npm install react@rc react-dom@rc leaflet

Then you can install React Leaflet:

npm install react-leaflet@next

Modules can then be imported using bare specifiers when supported by a bundler such as webpack.

import { MapContainer } from 'react-leaflet/MapContainer'
import { TileLayer } from 'react-leaflet/TileLayer'
import { useMap } from 'react-leaflet/hooks'

Alternatively, all the components and hooks can be imported from the module entry-point:

import { MapContainer, TileLayer, useMap } from 'react-leaflet'

TypeScript support​

Dependencies​

React Leaflet provides TypeScript definitions in the installed packages, but needs Leaflet's definitions to be present. If you have not installed them yet, you will need to add them:

npm install -D @types/leaflet

Imports​

TypeScript definitions are only exported from the package entry-point, so you should import from it directly when using TypeScript:

// ⚠️ No types available here
import { MapContainer } from 'react-leaflet/MapContainer'

// ✅ Types are available here
import { MapContainer } from 'react-leaflet'