Dash Leaflet

1.1.3 verified Fri May 01 auth: no python

A Dash component library for interactive maps, wrapping React-Leaflet. Provides Map, TileLayer, Marker, Popup, GeoJSON, and other Leaflet components for Python Dash apps. Current version: 1.1.3, released 2024-09. Active development with occasional breaking changes when aligning with React-Leaflet updates.

pip install dash-leaflet

Common errors

error ImportError: cannot import name 'Map' from 'dash_leaflet' ↓

cause Using `from dash_leaflet import Map` instead of importing the module and using dl.Map.

fix

Use import dash_leaflet as dl then dl.Map(...).

error AttributeError: module 'dash_leaflet' has no attribute 'Map' ↓

cause Older version of dash-leaflet (<1.0) or incorrect import. Also if using `import dash_leaflet` without alias.

fix

Upgrade: pip install --upgrade dash-leaflet, and always use import dash_leaflet as dl.

error TypeError: 'NoneType' object is not iterable ↓

cause Passing `center` as None or forgetting to set it. Map requires center and zoom.

fix

Always provide center=[lat, lng] and zoom=int.

error dash.exceptions.InvalidCallbackReturnValue: The callback ... returned a value of type ... which is not JSON serializable. ↓

cause Returning a Python dict or object that is not JSON-serializable in a callback's output that expects a component property (e.g., center, zoom).

fix

Ensure callback returns plain lists/dicts (JSON-compatible) for map properties.

error Leaflet map not visible (blank white area) ↓

cause Missing `style` prop on Map component; default height is 0.

fix

Add style={'width': '100%', 'height': '500px'} to the Map component.

Warnings

breaking Version 1.0.0+ changed from 'children' prop to nested children for Map and other components. Old syntax using 'children' as a prop no longer works. ↓

fix Replace dl.Map(children=[...]) with dl.Map([...]) or use children keyword but ensure it's a list of components.

gotcha The center prop for Map must be a list of two floats [lat, lng], not a tuple or dict. Many users mistakenly pass a dict like {'lat': 51.5, 'lng': -0.09}. ↓

fix Use center=[51.5, -0.09]

deprecated The 'children' prop in dl.Marker, dl.Polyline, etc. is deprecated in favor of placing popups/tooltips as children directly. Using children=dl.Popup(...) still works but may be removed in future. ↓

fix Place dl.Popup as a child element: dl.Marker(position=[...], children=[dl.Popup('text')])

gotcha GeoJSON data must be a dictionary (GeoJSON FeatureCollection), not a JSON string or file path. Common mistake: loading with json.loads and passing the string directly. ↓

fix Use: import json; with open('data.geojson') as f: data = json.load(f); dl.GeoJSON(data=data)

gotcha The 'style' prop on Map must be a valid CSS object (dictionary), not a string. Missing style may cause the map to not render (height defaults to 0). ↓

fix Set style={'width': '100%', 'height': '500px'} on the Map component.

Imports

dl
wrong
```
import dash_leaflet
```
correct
```
import dash_leaflet as dl
```
Functions as dl.Map, dl.TileLayer, etc. Using dash_leaflet.Map fails.

Map

wrong

dl.Map(children=[...], center=dict(lat=..., lng=...), zoom=10)

correct

dl.Map(children=[...], center=[lat, lng], zoom=10, style={'height': '500px'})

center must be a list [lat, lng], not a dict.

Quickstart

Creates a simple Dash app with a Leaflet map centered on London, including a tile layer and a marker with a popup.

import dash
from dash import html
import dash_leaflet as dl

app = dash.Dash(__name__)

app.layout = html.Div([
    dl.Map(center=[51.505, -0.09], zoom=13, children=[
        dl.TileLayer(),
        dl.Marker(position=[51.505, -0.09], children=[
            dl.Popup('Hello London')
        ])
    ], style={'width': '100%', 'height': '50vh'}, id='map')
])

if __name__ == '__main__':
    app.run_server(debug=True)