React Leaflet provides React components that wrap the Leaflet map library, offering a declarative way to integrate interactive maps into React applications. It abstracts Leaflet's imperative API into a set of composable React components, making it easier to manage map state and layers. The current stable version is 5.0.0, which requires React v19 and Leaflet v1.9.0 as peer dependencies. The library generally follows the major version releases of React and Leaflet, introducing breaking changes when these core dependencies update significantly. Its primary differentiator is providing a idiomatic React experience for Leaflet, avoiding direct DOM manipulation often associated with Leaflet's vanilla JavaScript API, and offering a robust, type-safe (TypeScript-friendly) development experience for geospatial applications within the React ecosystem.
npm install react-leafletVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to set up a basic Leaflet map in a React component using `react-leaflet`, including a `TileLayer` and a `Marker` with a `Popup`. It also addresses a common issue with missing default marker icons.
Update your `react` and `react-dom` packages to `^19.0.0` in your `package.json` and reinstall dependencies.
Review your code for `LeafletProvider` usage. It's likely you no longer need it, as context is typically managed internally by `MapContainer`.
Ensure your project is configured for ESM. Replace all `require('react-leaflet')` statements with `import { ... } from 'react-leaflet'`.For `whenCreated`, use a `ref` callback on `MapContainer` instead. For `useMapElement` and `MapConsumer`, use the `useMap` or `useMapEvents` hooks. For `Popup` and `Tooltip` events, rely on Leaflet's event system directly.
Explicitly set the `iconRetinaUrl`, `iconUrl`, and `shadowUrl` for `L.Icon.Default.prototype` before rendering any markers, or configure your bundler to handle static assets correctly. See the Quickstart example for a common workaround.
Upgrade `react` and `react-dom` to `^19.0.0` (for `react-leaflet` v5) or `^18.0.0` (for `react-leaflet` v4).
Import Leaflet explicitly and then use `L.Icon.Default.mergeOptions` to provide direct URLs for the marker assets (e.g., from unpkg.com) before any `Marker` components are rendered. Also ensure `import 'leaflet/dist/leaflet.css';` is included.
Change all `const { MapContainer } = require('react-leaflet');` statements to `import { MapContainer } from 'react-leaflet';` and ensure your project is configured for ESM.