`.
+
+.. toctree::
+ :maxdepth: 2
+
+ user_guide/map
+ user_guide/ui_elements
+ user_guide/raster_layers
+ user_guide/vector_layers
+ user_guide/geojson
+ user_guide/features
+ user_guide/plugins
diff --git a/docs/user_guide/features.rst b/docs/user_guide/features.rst
new file mode 100644
index 0000000000..99455a4277
--- /dev/null
+++ b/docs/user_guide/features.rst
@@ -0,0 +1,8 @@
+Features
+--------------------------
+
+.. toctree::
+ :maxdepth: 1
+
+ features/fit_overlays
+ features/click_related_classes
diff --git a/docs/user_guide/features/click_related_classes.md b/docs/user_guide/features/click_related_classes.md
new file mode 100644
index 0000000000..9996a7a784
--- /dev/null
+++ b/docs/user_guide/features/click_related_classes.md
@@ -0,0 +1,65 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+### Click-related classes
+
+#### ClickForMarker
+
+`ClickForMarker` lets you create markers on each click.
+
+```{code-cell} ipython3
+folium.Map().add_child(
+ folium.ClickForMarker()
+)
+```
+
+*Click on the map to see the effects*
+
+You can customize the popup by providing a string, an IFrame object or an Html object. You can include the latitude and longitude of the marker by using `${lat}` and `${lng}`.
+
+```{code-cell} ipython3
+folium.Map().add_child(
+ folium.ClickForMarker("Lat: ${lat}
Lon: ${lng}")
+)
+```
+
+*Click on the map to see the effects*
+
+
+#### LatLngPopup
+
+`LatLngPopup` lets you create a simple popup at each click.
+
+```{code-cell} ipython3
+folium.Map().add_child(
+ folium.LatLngPopup()
+)
+```
+
+*Click on the map to see the effects*
+
++++
+
+#### ClickForLatLng
+
+`ClickForLatLng` lets you copy coordinates to your browser clipboard.
+
+```{code-cell} ipython3
+folium.Map().add_child(
+ folium.ClickForLatLng(format_str='"[" + lat + "," + lng + "]"', alert=True)
+)
+```
+
+*Click on the map to see the effects*
+
+If you want to collect back the information in python, you may (install and) import the [clipboard](https://github.com/terryyin/clipboard) library:
+
+```
+>>> import clipboard
+>>> clipboard.paste()
+[-43.580391,-123.824467]
+```
diff --git a/docs/user_guide/features/fit_overlays.md b/docs/user_guide/features/fit_overlays.md
new file mode 100644
index 0000000000..e4ba74dca1
--- /dev/null
+++ b/docs/user_guide/features/fit_overlays.md
@@ -0,0 +1,40 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+## FitOverlays
+
+When you add this class to your map, the map will pan and zoom to fit the enabled overlays.
+
+By default, the map won't necessarily show all elements that were added. You may have to pan or zoom out to find them.
+
+If we add the `FitOverlays` class, it will automatically pan and zoom to show the enabled overlays.
+In this example we show only the first marker by default. If you enable the second marker, the view changes to include it.
+
+```{code-cell} ipython3
+m = folium.Map((52, 0), tiles='cartodbpositron', zoom_start=8)
+
+fg1 = folium.FeatureGroup().add_to(m)
+folium.Marker((52, 5)).add_to(fg1)
+
+fg2 = folium.FeatureGroup(show=False).add_to(m)
+folium.Marker((52, 5.1)).add_to(fg2)
+
+folium.FitOverlays().add_to(m)
+
+folium.LayerControl().add_to(m)
+
+m
+```
+
+`FitOverlays` has a couple options:
+
+- `padding` adds pixels around the bounds.
+- `max_zoom` can be used to prevent zooming in too far.
+- `fly` enables a smoother, longer animation, so you can see how the view changes.
+- `fit_on_map_load` can be used to disable the fitting that happens when the map loads.
+
+Note that `padding` and `max_zoom` can achieve the same effect.
diff --git a/docs/user_guide/geojson.rst b/docs/user_guide/geojson.rst
new file mode 100644
index 0000000000..704dc2e4b1
--- /dev/null
+++ b/docs/user_guide/geojson.rst
@@ -0,0 +1,12 @@
+GeoJSON and choropleth
+--------------------------
+
+.. toctree::
+ :maxdepth: 2
+
+ geojson/geojson
+ geojson/choropleth
+ geojson/geojson_marker
+ geojson/geojson_popup_and_tooltip
+ geojson/geopandas_and_geo_interface
+ geojson/smoothing
diff --git a/docs/user_guide/geojson/choropleth.md b/docs/user_guide/geojson/choropleth.md
new file mode 100644
index 0000000000..540cd2f259
--- /dev/null
+++ b/docs/user_guide/geojson/choropleth.md
@@ -0,0 +1,132 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+## Using `Choropleth`
+
+Now if you want to get faster, you can use the `Choropleth` class. Have a look at it's docstring, it has several styling options.
+
+Just like the `GeoJson` class you can provide it a filename, a dict, or a geopandas object.
+
+```{code-cell} ipython3
+import requests
+
+m = folium.Map([43, -100], zoom_start=4)
+
+us_states = requests.get(
+ "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
+).json()
+
+folium.Choropleth(
+ geo_data=us_states,
+ fill_opacity=0.3,
+ line_weight=2,
+).add_to(m)
+
+m
+```
+
+Then, in playing with keyword arguments, you can get a choropleth in a few lines:
+
+```{code-cell} ipython3
+import pandas
+
+state_data = pandas.read_csv(
+ "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_unemployment_oct_2012.csv"
+)
+
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.Choropleth(
+ geo_data=us_states,
+ data=state_data,
+ columns=["State", "Unemployment"],
+ key_on="feature.id",
+).add_to(m)
+
+m
+```
+
+You can force the color scale to a given number of bins (or directly list the bins you would like), by providing the `bins` argument.
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.Choropleth(
+ geo_data=us_states,
+ data=state_data,
+ columns=["State", "Unemployment"],
+ key_on="feature.id",
+ fill_color="YlGn",
+ bins=[3, 4, 9, 11],
+).add_to(m)
+
+m
+```
+
+You can also enable the highlight function, to enable highlight functionality when you hover over each area.
+
+```{code-cell} ipython3
+m = folium.Map(location=[48, -102], zoom_start=3)
+folium.Choropleth(
+ geo_data=us_states,
+ data=state_data,
+ columns=["State", "Unemployment"],
+ key_on="feature.id",
+ fill_color="YlGn",
+ fill_opacity=0.7,
+ line_opacity=0.2,
+ legend_name="Unemployment Rate (%)",
+ highlight=True,
+).add_to(m)
+
+m
+```
+
+You can customize the way missing and `nan` values are displayed on your map using the two parameters `nan_fill_color` and `nan_fill_opacity`.
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+messed_up_data = state_data.drop(0)
+messed_up_data.loc[4, "Unemployment"] = float("nan")
+
+folium.Choropleth(
+ geo_data=us_states,
+ data=messed_up_data,
+ columns=["State", "Unemployment"],
+ nan_fill_color="purple",
+ nan_fill_opacity=0.4,
+ key_on="feature.id",
+ fill_color="YlGn",
+).add_to(m)
+
+m
+```
+
+Internally Choropleth uses the `GeoJson` or `TopoJson` class, depending on your settings, and the `StepColormap` class. Both objects are attributes of your `Choropleth` object called `geojson` and `color_scale`. You can make changes to them, but for regular things you won't have to. For example setting a name for in the layer controls or disabling showing the layer on opening the map is possible in `Choropleth` itself.
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+choropleth = folium.Choropleth(
+ geo_data=us_states,
+ data=state_data,
+ columns=["State", "Unemployment"],
+ key_on="feature.id",
+ fill_color="YlGn",
+ name="Unenployment",
+ show=False,
+).add_to(m)
+
+# The underlying GeoJson and StepColormap objects are reachable
+print(type(choropleth.geojson))
+print(type(choropleth.color_scale))
+
+folium.LayerControl(collapsed=False).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/geojson/geojson.md b/docs/user_guide/geojson/geojson.md
new file mode 100644
index 0000000000..5a5207f3b8
--- /dev/null
+++ b/docs/user_guide/geojson/geojson.md
@@ -0,0 +1,238 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+## Using `GeoJson`
+
+### Loading data
+
+Let us load a GeoJSON file representing the US states.
+
+```{code-cell} ipython3
+import requests
+
+geo_json_data = requests.get(
+ "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
+).json()
+```
+
+It is a classical GeoJSON `FeatureCollection` (see https://en.wikipedia.org/wiki/GeoJSON) of the form :
+
+ {
+ "type": "FeatureCollection",
+ "features": [
+ {
+ "properties": {"name": "Alabama"},
+ "id": "AL",
+ "type": "Feature",
+ "geometry": {
+ "type": "Polygon",
+ "coordinates": [[[-87.359296, 35.00118], ...]]
+ }
+ },
+ {
+ "properties": {"name": "Alaska"},
+ "id": "AK",
+ "type": "Feature",
+ "geometry": {
+ "type": "MultiPolygon",
+ "coordinates": [[[[-131.602021, 55.117982], ... ]]]
+ }
+ },
+ ...
+ ]
+ }
+
+A first way of drawing it on a map, is simply to use `folium.GeoJson` :
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.GeoJson(geo_json_data).add_to(m)
+
+m
+```
+
+Note that you can avoid loading the file on yourself,
+by providing a (local) file path or a url.
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+url = "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
+
+folium.GeoJson(url).add_to(m)
+
+m
+```
+
+You can pass a geopandas object.
+
+```{code-cell} ipython3
+import geopandas
+
+gdf = geopandas.read_file(url)
+
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.GeoJson(
+ gdf,
+).add_to(m)
+
+m
+```
+
+### Click on zoom
+
+You can enable an option that if you click on a part of the geometry the map will zoom in to that.
+
+Try it on the map below:
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.GeoJson(geo_json_data, zoom_on_click=True).add_to(m)
+
+m
+```
+
+### Styling
+
+Now this is cool and simple, but we may be willing to choose the style of the data.
+
+You can provide a function of the form `lambda feature: {}` that sets the style of each feature.
+
+For possible options, see:
+
+* For `Point` and `MultiPoint`, see https://leafletjs.com/reference.html#marker
+* For other features, see https://leafletjs.com/reference.html#path and https://leafletjs.com/reference.html#polyline
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.GeoJson(
+ geo_json_data,
+ style_function=lambda feature: {
+ "fillColor": "#ffff00",
+ "color": "black",
+ "weight": 2,
+ "dashArray": "5, 5",
+ },
+).add_to(m)
+
+m
+```
+
+What's cool in providing a function, is that you can specify a style depending on the feature. For example, if you want to visualize in green all states whose name contains the letter 'E', just do:
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.GeoJson(
+ geo_json_data,
+ style_function=lambda feature: {
+ "fillColor": "green"
+ if "e" in feature["properties"]["name"].lower()
+ else "#ffff00",
+ "color": "black",
+ "weight": 2,
+ "dashArray": "5, 5",
+ },
+).add_to(m)
+
+m
+```
+
+Wow, this looks almost like a choropleth. To do one, we just need to compute a color for each state.
+
+Let's imagine we want to draw a choropleth of unemployment in the US.
+
+First, we may load the data:
+
+```{code-cell} ipython3
+import pandas
+
+unemployment = pandas.read_csv(
+ "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_unemployment_oct_2012.csv"
+)
+
+unemployment.head(5)
+```
+
+Now we need to create a function that maps one value to a RGB color (of the form `#RRGGBB`).
+For this, we'll use colormap tools from `folium.colormap`.
+
+```{code-cell} ipython3
+from branca.colormap import linear
+
+colormap = linear.YlGn_09.scale(
+ unemployment.Unemployment.min(), unemployment.Unemployment.max()
+)
+
+print(colormap(5.0))
+
+colormap
+```
+
+We need also to convert the table into a dictionary, in order to map a feature to it's unemployment value.
+
+```{code-cell} ipython3
+unemployment_dict = unemployment.set_index("State")["Unemployment"]
+
+unemployment_dict["AL"]
+```
+
+Now we can do the choropleth.
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.GeoJson(
+ geo_json_data,
+ name="unemployment",
+ style_function=lambda feature: {
+ "fillColor": colormap(unemployment_dict[feature["id"]]),
+ "color": "black",
+ "weight": 1,
+ "dashArray": "5, 5",
+ "fillOpacity": 0.9,
+ },
+).add_to(m)
+
+folium.LayerControl().add_to(m)
+
+m
+```
+
+Of course, if you can create and/or use a dictionary providing directly the good color. Thus, the finishing seems faster:
+
+```{code-cell} ipython3
+color_dict = {key: colormap(unemployment_dict[key]) for key in unemployment_dict.keys()}
+```
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+folium.GeoJson(
+ geo_json_data,
+ style_function=lambda feature: {
+ "fillColor": color_dict[feature["id"]],
+ "color": "black",
+ "weight": 1,
+ "dashArray": "5, 5",
+ "fillOpacity": 0.9,
+ },
+).add_to(m)
+```
+
+Note that adding a color legend may be a good idea.
+
+```{code-cell} ipython3
+colormap.caption = "Unemployment color scale"
+colormap.add_to(m)
+
+m
+```
diff --git a/docs/user_guide/geojson/geojson_marker.md b/docs/user_guide/geojson/geojson_marker.md
new file mode 100644
index 0000000000..5f9505d458
--- /dev/null
+++ b/docs/user_guide/geojson/geojson_marker.md
@@ -0,0 +1,115 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+# GeoJSON point features with markers
+
+
+```{code-cell} ipython3
+import geopandas
+
+gdf = geopandas.read_file(
+ "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/subway_stations.geojson"
+)
+
+gdf.head()
+```
+
+```{code-cell} ipython3
+gdf['href'] = '' + gdf.url + ""
+gdf['service_level'] = gdf.notes.str.split(', ').apply(lambda x: len([v for v in x if "all" in v]))
+gdf['lines_served'] = gdf.line.str.split('-').apply(lambda x: len(x))
+```
+
+```{code-cell} ipython3
+service_levels = gdf.service_level.unique().tolist()
+service_levels
+```
+
+```{code-cell} ipython3
+colors = ["orange", "yellow", "green", "blue"]
+```
+
+## Use a Circle as a Marker
+
+```{code-cell} ipython3
+m = folium.Map(location=[40.75, -73.95], zoom_start=13)
+
+folium.GeoJson(
+ gdf,
+ name="Subway Stations",
+ marker=folium.Circle(radius=4, fill_color="orange", fill_opacity=0.4, color="black", weight=1),
+ tooltip=folium.GeoJsonTooltip(fields=["name", "line", "notes"]),
+ popup=folium.GeoJsonPopup(fields=["name", "line", "href", "notes"]),
+ style_function=lambda x: {
+ "fillColor": colors[x['properties']['service_level']],
+ "radius": (x['properties']['lines_served'])*30,
+ },
+ highlight_function=lambda x: {"fillOpacity": 0.8},
+ zoom_on_click=True,
+).add_to(m)
+
+m
+```
+
+## Or use a DivIcon
+
+```{code-cell} ipython3
+m = folium.Map(location=[40.75, -73.95], zoom_start=13)
+
+
+def style_function(feature):
+ props = feature.get('properties')
+ markup = f"""
+
+
+
+
+ {props.get('name')}
+
lat:{}".format(lon, lat) for (lat, lon) in locations]
+```
+
+## Adding all icons in a single call
+
+```{code-cell} ipython3
+icon_create_function = """\
+function(cluster) {
+ return L.divIcon({
+ html: '' + cluster.getChildCount() + '',
+ className: 'marker-cluster marker-cluster-large',
+ iconSize: new L.Point(20, 20)
+ });
+}"""
+```
+
+```{code-cell} ipython3
+from folium.plugins import MarkerCluster
+
+m = folium.Map(
+ location=[np.mean(lats), np.mean(lons)], tiles="Cartodb Positron", zoom_start=1
+)
+
+marker_cluster = MarkerCluster(
+ locations=locations,
+ popups=popups,
+ name="1000 clustered icons",
+ overlay=True,
+ control=True,
+ icon_create_function=icon_create_function,
+)
+
+marker_cluster.add_to(m)
+
+folium.LayerControl().add_to(m)
+
+m
+```
+
+## Explicit loop allows for customization in the loop.
+
+```{code-cell} ipython3
+m = folium.Map(
+ location=[np.mean(lats), np.mean(lons)],
+ tiles='Cartodb Positron',
+ zoom_start=1
+)
+
+marker_cluster = MarkerCluster(
+ name='1000 clustered icons',
+ overlay=True,
+ control=False,
+ icon_create_function=None
+)
+
+for k in range(size):
+ location = lats[k], lons[k]
+ marker = folium.Marker(location=location)
+ popup = 'lon:{}
lat:{}'.format(location[1], location[0])
+ folium.Popup(popup).add_to(marker)
+ marker_cluster.add_child(marker)
+
+marker_cluster.add_to(m)
+
+folium.LayerControl().add_to(m);
+
+m
+```
+
+## FastMarkerCluster
+
+`FastMarkerCluster` is not as flexible as MarkerCluster but, like the name suggests, it is faster.
+
+```{code-cell} ipython3
+from folium.plugins import FastMarkerCluster
+
+m = folium.Map(
+ location=[np.mean(lats), np.mean(lons)],
+ tiles='Cartodb Positron',
+ zoom_start=1
+)
+
+FastMarkerCluster(data=list(zip(lats, lons))).add_to(m)
+
+folium.LayerControl().add_to(m);
+
+m
+```
+
+```{code-cell} ipython3
+callback = """\
+function (row) {
+ var icon, marker;
+ icon = L.AwesomeMarkers.icon({
+ icon: "map-marker", markerColor: "red"});
+ marker = L.marker(new L.LatLng(row[0], row[1]));
+ marker.setIcon(icon);
+ return marker;
+};
+"""
+
+m = folium.Map(
+ location=[np.mean(lats), np.mean(lons)], tiles="Cartodb Positron", zoom_start=1
+)
+
+FastMarkerCluster(data=list(zip(lats, lons)), callback=callback).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/measure_control.md b/docs/user_guide/plugins/measure_control.md
new file mode 100644
index 0000000000..b15df96558
--- /dev/null
+++ b/docs/user_guide/plugins/measure_control.md
@@ -0,0 +1,14 @@
+# MeasureControl
+
+This plugin allows you to measure distances on the map.
+
+```{code-cell} ipython3
+import folium
+from folium.plugins import MeasureControl
+
+m = folium.Map([-27.5717, -48.6256], zoom_start=10)
+
+m.add_child(MeasureControl())
+
+m
+```
diff --git a/docs/user_guide/plugins/mini_map.md b/docs/user_guide/plugins/mini_map.md
new file mode 100644
index 0000000000..0685919006
--- /dev/null
+++ b/docs/user_guide/plugins/mini_map.md
@@ -0,0 +1,52 @@
+## MiniMap
+
+```{code-cell} ipython3
+import folium
+from folium.plugins import MiniMap
+
+m = folium.Map(location=(30, 20), zoom_start=4)
+
+MiniMap().add_to(m)
+
+m
+```
+
+### Make the minimap collapsible
+
+```{code-cell} ipython3
+m = folium.Map(location=(30, 20), zoom_start=4)
+MiniMap(toggle_display=True).add_to(m)
+m
+```
+
+### Change the minimap tile layer
+
+```{code-cell} ipython3
+m = folium.Map(location=(30, 20), zoom_start=4)
+MiniMap(tile_layer="Stamen Toner").add_to(m)
+m
+```
+
+### Change the minimap position
+
+```{code-cell} ipython3
+m = folium.Map(location=(30, 20), zoom_start=4)
+MiniMap(position="topleft").add_to(m)
+m
+```
+
+### Change the minimap size
+
+```{code-cell} ipython3
+m = folium.Map(location=(30, 20), zoom_start=4)
+MiniMap(width=400, height=100).add_to(m)
+m
+```
+
+### Change the zoom offset
+
+```{code-cell} ipython3
+m = folium.Map(location=(30, 20), zoom_start=8)
+MiniMap(zoom_level_offset=-8).add_to(m)
+m
+```
diff --git a/docs/user_guide/plugins/mouse_position.md b/docs/user_guide/plugins/mouse_position.md
new file mode 100644
index 0000000000..823054d173
--- /dev/null
+++ b/docs/user_guide/plugins/mouse_position.md
@@ -0,0 +1,37 @@
+# MousePosition
+
+This plugin adds a small field to your map that shows the coordinates of your mouse position.
+By default it is in the bottom right corner.
+
+```{code-cell} ipython3
+import folium
+from folium.plugins import MousePosition
+
+
+m = folium.Map()
+
+MousePosition().add_to(m)
+
+m
+```
+
+## Options
+
+```{code-cell} ipython3
+m = folium.Map()
+
+formatter = "function(num) {return L.Util.formatNum(num, 3) + ' ° ';};"
+
+MousePosition(
+ position="topright",
+ separator=" | ",
+ empty_string="NaN",
+ lng_first=True,
+ num_digits=20,
+ prefix="Coordinates:",
+ lat_formatter=formatter,
+ lng_formatter=formatter,
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/pattern.md b/docs/user_guide/plugins/pattern.md
new file mode 100644
index 0000000000..74dbf130b4
--- /dev/null
+++ b/docs/user_guide/plugins/pattern.md
@@ -0,0 +1,54 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+# Pattern plugins
+
+We have two pattern plugin classes: `StripePattern` and `CirclePattern`.
+
+```{code-cell} ipython3
+import requests
+
+m = folium.Map([40.0, -105.0], zoom_start=6)
+
+stripes = folium.plugins.pattern.StripePattern(angle=-45).add_to(m)
+
+circles = folium.plugins.pattern.CirclePattern(
+ width=20, height=20, radius=5, fill_opacity=0.5, opacity=1
+).add_to(m)
+
+
+def style_function(feature):
+ default_style = {
+ "opacity": 1.0,
+ "fillColor": "#ffff00",
+ "color": "black",
+ "weight": 2,
+ }
+
+ if feature["properties"]["name"] == "Colorado":
+ default_style["fillPattern"] = stripes
+ default_style["fillOpacity"] = 1.0
+
+ if feature["properties"]["name"] == "Utah":
+ default_style["fillPattern"] = circles
+ default_style["fillOpacity"] = 1.0
+
+ return default_style
+
+us_states = requests.get(
+ "https://raw.githubusercontent.com/python-visualization/folium-example-data/main/us_states.json"
+).json()
+
+folium.GeoJson(
+ us_states,
+ smooth_factor=0.5,
+ style_function=style_function,
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/polyline_offset.md b/docs/user_guide/plugins/polyline_offset.md
new file mode 100644
index 0000000000..e12fade8d8
--- /dev/null
+++ b/docs/user_guide/plugins/polyline_offset.md
@@ -0,0 +1,204 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+# PolylineOffset
+
+## Basic Demo
+
+- The dashed line is the "model", with no offset applied.
+- The Red line is with a -5px offset,
+- The Green line is with a 10px offset.
+The three are distinct Polyline objects but uses the same coordinate array
+
+```{code-cell} ipython3
+m = folium.Map(location=[58.0, -11.0], zoom_start=4, tiles="cartodbpositron")
+
+coords = [
+ [58.44773, -28.65234],
+ [53, -23.33496],
+ [53, -14.32617],
+ [58.1707, -10.37109],
+ [59, -13],
+ [57, -15],
+ [57, -18],
+ [60, -18],
+ [63, -5],
+ [59, -7],
+ [58, -3],
+ [56, -3],
+ [60, -4],
+]
+
+folium.plugins.PolyLineOffset(
+ coords, weight=2, dash_array="5,10", color="black", opacity=1
+).add_to(m)
+
+folium.plugins.PolyLineOffset(coords, color="#f00", opacity=1, offset=-5).add_to(m)
+
+folium.plugins.PolyLineOffset(coords, color="#080", opacity=1, offset=10).add_to(m)
+
+m
+```
+
+## Bus Lines
+
+A more complex demo.
+Offsets are computed automatically depending on the number of bus lines using the same segment.
+Other non-offset polylines are used to achieve the white and black outline effect.
+
+```{code-cell} ipython3
+m = folium.Map(location=[48.868, 2.365], zoom_start=15)
+
+geojson = {
+ "type": "FeatureCollection",
+ "features": [
+ {
+ "type": "Feature",
+ "properties": {"lines": [0, 1]},
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [2.357919216156006, 48.87621773324153],
+ [2.357339859008789, 48.874834693731664],
+ [2.362983226776123, 48.86855408432749],
+ [2.362382411956787, 48.86796126699168],
+ [2.3633265495300293, 48.86735432768131],
+ ],
+ },
+ },
+ {
+ "type": "Feature",
+ "properties": {"lines": [2, 3]},
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [2.351503372192383, 48.86443950493823],
+ [2.361609935760498, 48.866775611250205],
+ [2.3633265495300293, 48.86735432768131],
+ ],
+ },
+ },
+ {
+ "type": "Feature",
+ "properties": {"lines": [1, 2]},
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [2.369627058506012, 48.86619159489603],
+ [2.3724031448364253, 48.8626397112042],
+ [2.3728322982788086, 48.8616233285001],
+ [2.372767925262451, 48.86080456075567],
+ ],
+ },
+ },
+ {
+ "type": "Feature",
+ "properties": {"lines": [0]},
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [2.3647427558898926, 48.86653565369396],
+ [2.3647642135620117, 48.86630981023694],
+ [2.3666739463806152, 48.86314789481612],
+ [2.3673176765441895, 48.86066339254944],
+ ],
+ },
+ },
+ {
+ "type": "Feature",
+ "properties": {"lines": [0, 1, 2, 3]},
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [2.3633265495300293, 48.86735432768131],
+ [2.3647427558898926, 48.86653565369396],
+ ],
+ },
+ },
+ {
+ "type": "Feature",
+ "properties": {"lines": [1, 2, 3]},
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [2.3647427558898926, 48.86653565369396],
+ [2.3650002479553223, 48.86660622956524],
+ [2.365509867668152, 48.866987337550164],
+ [2.369627058506012, 48.86619159489603],
+ ],
+ },
+ },
+ {
+ "type": "Feature",
+ "properties": {"lines": [3]},
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [2.369627058506012, 48.86619159489603],
+ [2.372349500656128, 48.865702850895744],
+ ],
+ },
+ },
+ ],
+}
+
+# manage overlays in groups to ease superposition order
+outlines = folium.FeatureGroup("outlines")
+line_bg = folium.FeatureGroup("lineBg")
+bus_lines = folium.FeatureGroup("busLines")
+bus_stops = folium.FeatureGroup("busStops")
+
+line_weight = 6
+line_colors = ["red", "#08f", "#0c0", "#f80"]
+stops = []
+for line_segment in geojson["features"]:
+ # Get every bus line coordinates
+ segment_coords = [[x[1], x[0]] for x in line_segment["geometry"]["coordinates"]]
+ # Get bus stops coordinates
+ stops.append(segment_coords[0])
+ stops.append(segment_coords[-1])
+ # Get number of bus lines sharing the same coordinates
+ lines_on_segment = line_segment["properties"]["lines"]
+ # Width of segment proportional to the number of bus lines
+ segment_width = len(lines_on_segment) * (line_weight + 1)
+ # For the white and black outline effect
+ folium.PolyLine(
+ segment_coords, color="#000", weight=segment_width + 5, opacity=1
+ ).add_to(outlines)
+ folium.PolyLine(
+ segment_coords, color="#fff", weight=segment_width + 3, opacity=1
+ ).add_to(line_bg)
+ # Draw parallel bus lines with different color and offset
+ for j, line_number in enumerate(lines_on_segment):
+ folium.plugins.PolyLineOffset(
+ segment_coords,
+ color=line_colors[line_number],
+ weight=line_weight,
+ opacity=1,
+ offset=j * (line_weight + 1) - (segment_width / 2) + ((line_weight + 1) / 2),
+ ).add_to(bus_lines)
+
+# Draw bus stops
+for stop in stops:
+ folium.CircleMarker(
+ stop,
+ color="#000",
+ fill_color="#ccc",
+ fill_opacity=1,
+ radius=10,
+ weight=4,
+ opacity=1,
+ ).add_to(bus_stops)
+
+outlines.add_to(m)
+line_bg.add_to(m)
+bus_lines.add_to(m)
+bus_stops.add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/polyline_textpath_and_antpath.md b/docs/user_guide/plugins/polyline_textpath_and_antpath.md
new file mode 100644
index 0000000000..d45374b8d8
--- /dev/null
+++ b/docs/user_guide/plugins/polyline_textpath_and_antpath.md
@@ -0,0 +1,108 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+# PolylineTextPath and AntPath
+
+
+## PolyLineTextPath
+
+```{code-cell} ipython3
+m = folium.Map([30, 0], zoom_start=3)
+
+wind_locations = [
+ [59.35560, -31.992190],
+ [55.178870, -42.89062],
+ [47.754100, -43.94531],
+ [38.272690, -37.96875],
+ [27.059130, -41.13281],
+ [16.299050, -36.56250],
+ [8.4071700, -30.23437],
+ [1.0546300, -22.50000],
+ [-8.754790, -18.28125],
+ [-21.61658, -20.03906],
+ [-31.35364, -24.25781],
+ [-39.90974, -30.93750],
+ [-43.83453, -41.13281],
+ [-47.75410, -49.92187],
+ [-50.95843, -54.14062],
+ [-55.97380, -56.60156],
+]
+
+wind_line = folium.PolyLine(wind_locations, weight=15, color="#8EE9FF").add_to(m)
+
+attr = {"fill": "#007DEF", "font-weight": "bold", "font-size": "24"}
+
+folium.plugins.PolyLineTextPath(
+ wind_line, ") ", repeat=True, offset=7, attributes=attr
+).add_to(m)
+
+danger_line = folium.PolyLine(
+ [[-40.311, -31.952], [-12.086, -18.727]], weight=10, color="orange", opacity=0.8
+).add_to(m)
+
+attr = {"fill": "red"}
+
+folium.plugins.PolyLineTextPath(
+ danger_line, "\u25BA", repeat=True, offset=6, attributes=attr
+).add_to(m)
+
+plane_line = folium.PolyLine(
+ [[-49.38237, -37.26562], [-1.75754, -14.41406], [51.61802, -23.20312]],
+ weight=1,
+ color="black",
+).add_to(m)
+
+attr = {"font-weight": "bold", "font-size": "24"}
+
+folium.plugins.PolyLineTextPath(
+ plane_line, "\u2708 ", repeat=True, offset=8, attributes=attr
+).add_to(m)
+
+
+line_to_new_delhi = folium.PolyLine(
+ [
+ [46.67959447, 3.33984375],
+ [46.5588603, 29.53125],
+ [42.29356419, 51.328125],
+ [35.74651226, 68.5546875],
+ [28.65203063, 76.81640625],
+ ]
+).add_to(m)
+
+
+line_to_hanoi = folium.PolyLine(
+ [
+ [28.76765911, 77.60742188],
+ [27.83907609, 88.72558594],
+ [25.68113734, 97.3828125],
+ [21.24842224, 105.77636719],
+ ]
+).add_to(m)
+
+
+folium.plugins.PolyLineTextPath(line_to_new_delhi, "To New Delhi", offset=-5).add_to(m)
+
+
+folium.plugins.PolyLineTextPath(line_to_hanoi, "To Hanoi", offset=-5).add_to(m)
+
+m
+```
+
+## Antpath
+
+```{code-cell} ipython3
+m = folium.Map()
+
+folium.plugins.AntPath(
+ locations=wind_locations, reverse="True", dash_array=[20, 30]
+).add_to(m)
+
+m.fit_bounds(m.get_bounds())
+
+m
+```
diff --git a/docs/user_guide/plugins/scroll_zoom_toggler.md b/docs/user_guide/plugins/scroll_zoom_toggler.md
new file mode 100644
index 0000000000..0fff09185c
--- /dev/null
+++ b/docs/user_guide/plugins/scroll_zoom_toggler.md
@@ -0,0 +1,19 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+## ScrollZoomToggler
+
+Add a button to enable/disable zoom scrolling.
+
+```{code-cell} ipython3
+m = folium.Map([45, 3], zoom_start=4)
+
+folium.plugins.ScrollZoomToggler().add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/search.md b/docs/user_guide/plugins/search.md
new file mode 100644
index 0000000000..2d5e2e5d65
--- /dev/null
+++ b/docs/user_guide/plugins/search.md
@@ -0,0 +1,151 @@
+# Search
+
+The `Search` plugin allows you to search in your `GeoJson`, `TopoJson`, `FeatureGroup` or `MarkerCluster` objects.
+
+## Data
+
+Let's get some JSON data from the web - both a point layer and a polygon GeoJson dataset with some population data.
+
+```{code-cell} ipython3
+import geopandas
+
+states = geopandas.read_file(
+ "https://raw.githubusercontent.com/PublicaMundi/MappingAPI/master/data/geojson/us-states.json",
+ driver="GeoJSON",
+)
+
+cities = geopandas.read_file(
+ "https://d2ad6b4ur7yvpq.cloudfront.net/naturalearth-3.3.0/ne_50m_populated_places_simple.geojson",
+ driver="GeoJSON",
+)
+```
+
+And take a look at what our data looks like:
+
+```{code-cell} ipython3
+states.describe()
+```
+
+Look how far the minimum and maximum values for the density are from the top and bottom quartile breakpoints! We have some outliers in our data that are well outside the meat of most of the distribution. Let's look into this to find the culprits within the sample.
+
+```{code-cell} ipython3
+import pandas as pd
+
+states_sorted = states.sort_values(by="density", ascending=False)
+
+pd.concat([
+ states_sorted.nlargest(5, 'density')[['name', 'density']],
+ states_sorted.nsmallest(5, 'density')[['name', 'density']]
+])
+```
+
+Looks like Washington D.C. and Alaska were the culprits on each end of the range. Washington was more dense than the next most dense state, New Jersey, than the least dense state, Alaska was from Wyoming, however. Washington D.C. has a has a relatively small land area for the amount of people that live there, so it makes sense that it's pretty dense. And Alaska has a lot of land area, but not much of it is habitable for humans.
+
+
+However, we're looking at all of the states in the US to look at things on a more regional level. That high figure at the top of our range for Washington D.C. will really hinder the ability for us to differentiate between the other states, so let's account for that in the min and max values for our color scale, by getting the quantile values close to the end of the range. Anything higher or lower than those values will just fall into the 'highest' and 'lowest' bins for coloring.
+
+```{code-cell} ipython3
+def rd2(x):
+ return round(x, 2)
+
+minimum, maximum = states["density"].quantile([0.05, 0.95]).apply(rd2)
+
+mean = round(states["density"].mean(), 2)
+
+print(f"minimum: {minimum}", f"maximum: {maximum}", f"Mean: {mean}", sep="\n\n")
+```
+
+This looks better. Our min and max values for the colorscale are much closer to the mean value now. Let's run with these values, and make a colorscale. I'm just going to use a sequential light-to-dark color palette from the [ColorBrewer](https://colorbrewer2.org/?type=sequential&scheme=Purples&n=5).
+
+```{code-cell} ipython3
+import branca
+
+
+colormap = branca.colormap.LinearColormap(
+ colors=["#f2f0f7", "#cbc9e2", "#9e9ac8", "#756bb1", "#54278f"],
+ index=states["density"].quantile([0.2, 0.4, 0.6, 0.8]),
+ vmin=minimum,
+ vmax=maximum,
+)
+
+colormap.caption = "Population Density in the United States"
+
+colormap
+```
+
+Let's narrow down these cities to United states cities, by using GeoPandas' spatial join functionality between two GeoDataFrame objects, using the Point 'within' Polygon functionality.
+
+```{code-cell} ipython3
+us_cities = geopandas.sjoin(cities, states, how="inner", predicate="within")
+
+pop_ranked_cities = us_cities.sort_values(by="pop_max", ascending=False)[
+ ["nameascii", "pop_max", "geometry"]
+].iloc[:20]
+```
+
+Ok, now we have a new GeoDataFrame with our top 20 populated cities. Let's see the top 5.
+
+```{code-cell} ipython3
+pop_ranked_cities.head(5)
+```
+
+## Map with Search plugin
+
+Alright, let's build a map!
+
+```{code-cell} ipython3
+import folium
+from folium.plugins import Search
+
+
+m = folium.Map(location=[38, -97], zoom_start=4)
+
+
+def style_function(x):
+ return {
+ "fillColor": colormap(x["properties"]["density"]),
+ "color": "black",
+ "weight": 2,
+ "fillOpacity": 0.5,
+ }
+
+
+stategeo = folium.GeoJson(
+ states,
+ name="US States",
+ style_function=style_function,
+ tooltip=folium.GeoJsonTooltip(
+ fields=["name", "density"], aliases=["State", "Density"], localize=True
+ ),
+).add_to(m)
+
+citygeo = folium.GeoJson(
+ pop_ranked_cities,
+ name="US Cities",
+ tooltip=folium.GeoJsonTooltip(
+ fields=["nameascii", "pop_max"], aliases=["", "Population Max"], localize=True
+ ),
+).add_to(m)
+
+statesearch = Search(
+ layer=stategeo,
+ geom_type="Polygon",
+ placeholder="Search for a US State",
+ collapsed=False,
+ search_label="name",
+ weight=3,
+).add_to(m)
+
+citysearch = Search(
+ layer=citygeo,
+ geom_type="Point",
+ placeholder="Search for a US City",
+ collapsed=True,
+ search_label="nameascii",
+).add_to(m)
+
+folium.LayerControl().add_to(m)
+colormap.add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/semi_circle.md b/docs/user_guide/plugins/semi_circle.md
new file mode 100644
index 0000000000..f7dcf31520
--- /dev/null
+++ b/docs/user_guide/plugins/semi_circle.md
@@ -0,0 +1,41 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+## SemiCircle
+
+This can be used to display a semicircle or sector on a map. Whilst called SemiCircle it is not limited to 180 degree angles and can be used to display a sector of any angle.
+
+The semicircle is defined with a location (the central point, if it was a full circle), a radius and will either have a direction and an arc **or** a start angle and a stop angle.
+
+```{code-cell} ipython3
+m = folium.Map([45, 3], zoom_start=5)
+
+folium.plugins.SemiCircle(
+ (45, 3),
+ radius=400000,
+ start_angle=50,
+ stop_angle=200,
+ color="green",
+ fill_color="green",
+ opacity=0,
+ popup="start angle - 50 degrees, stop angle - 200 degrees",
+).add_to(m)
+
+folium.plugins.SemiCircle(
+ (46.5, 9.5),
+ radius=200000,
+ direction=360,
+ arc=90,
+ color="red",
+ fill_color="red",
+ opacity=0,
+ popup="Direction - 0 degrees, arc 90 degrees",
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/side_by_side_layers.md b/docs/user_guide/plugins/side_by_side_layers.md
new file mode 100644
index 0000000000..7a2549adce
--- /dev/null
+++ b/docs/user_guide/plugins/side_by_side_layers.md
@@ -0,0 +1,30 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+## SideBySideLayers
+
+This plugin can be used to compare two layers on the same map using a vertical separator managed by the user.
+
+The SideBySideLayers class must be instantiated with left and right layers, then added to the map along with layers.
+
+If you want to add a layer control to your map, you can permanently enable the tile layers used for this plugin with `control=False`.
+
+```{code-cell} ipython3
+m = folium.Map(location=(30, 20), zoom_start=4)
+
+layer_right = folium.TileLayer('openstreetmap')
+layer_left = folium.TileLayer('cartodbpositron')
+
+sbs = folium.plugins.SideBySideLayers(layer_left=layer_left, layer_right=layer_right)
+
+layer_left.add_to(m)
+layer_right.add_to(m)
+sbs.add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/tag_filter_button.md b/docs/user_guide/plugins/tag_filter_button.md
new file mode 100644
index 0000000000..b3466f2554
--- /dev/null
+++ b/docs/user_guide/plugins/tag_filter_button.md
@@ -0,0 +1,39 @@
+# TagFilterButton
+
+```{code-cell} ipython3
+import os
+import folium
+```
+
+```{code-cell} ipython3
+import numpy as np
+import random
+
+# Generate base data
+data = (np.random.normal(size=(100, 2)) * np.array([[1, 1]]) +
+ np.array([[48, 5]]))
+# Generate the data to segment by (levels of another pandas column in practical usage)
+categories = ['category{}'.format(i+1) for i in range(5)]
+category_column = [random.choice(categories) for i in range(len(data))]
+```
+
+Create markers, and add tags to each marker. There can be multiple tags per marker, but in this example we add just one.
+
+Then, create the `TagFilterButton` object and let it know which tags you want to filter on.
+
+```{code-cell} ipython3
+from folium.plugins import TagFilterButton
+
+# Create map and add the data with additional parameter tags as the segmentation
+m = folium.Map([48., 5.], tiles='stamentoner', zoom_start=7)
+for i, latlng in enumerate(data):
+ category = category_column[i]
+ folium.Marker(
+ tuple(latlng),
+ tags=[category]
+ ).add_to(m)
+
+TagFilterButton(categories).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/terminator.md b/docs/user_guide/plugins/terminator.md
new file mode 100644
index 0000000000..003f313fcc
--- /dev/null
+++ b/docs/user_guide/plugins/terminator.md
@@ -0,0 +1,20 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+## Terminator
+
+This plugin overlays the current day and night regions on the map. It updates
+continuously. Zoom in in the example below to see the regions move.
+
+```{code-cell} ipython3
+m = folium.Map([45, 3], zoom_start=1)
+
+folium.plugins.Terminator().add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/timeslider_choropleth.md b/docs/user_guide/plugins/timeslider_choropleth.md
new file mode 100644
index 0000000000..8b9c942f41
--- /dev/null
+++ b/docs/user_guide/plugins/timeslider_choropleth.md
@@ -0,0 +1,182 @@
+# TimeSliderChoropleth
+
+In this example we'll make a choropleth with a timeslider.
+
+The class needs at least two arguments to be instantiated.
+
+1. A string-serielized geojson containing all the features (i.e., the areas)
+2. A dictionary with the following structure:
+
+```
+styledict = {
+ '0': {
+ '2017-1-1': {'color': 'ffffff', 'opacity': 1},
+ '2017-1-2': {'color': 'fffff0', 'opacity': 1},
+ ...
+ },
+ ...,
+ 'n': {
+ '2017-1-1': {'color': 'ffffff', 'opacity': 1},
+ '2017-1-2': {'color': 'fffff0', 'opacity': 1},
+ ...
+ }
+}
+```
+
+In the above dictionary, the keys are the feature-ids.
+
+Using both color and opacity gives us the ability to simultaneously visualize two features on the choropleth. I typically use color to visualize the main feature (like, average height) and opacity to visualize how many measurements were in that group.
+
+## Loading the features
+
+We use `geopandas` to load a dataset containing the boundaries of all the countries in the world.
+
+```{code-cell} ipython3
+import geopandas as gpd
+
+assert "naturalearth_lowres" in gpd.datasets.available
+datapath = gpd.datasets.get_path("naturalearth_lowres")
+gdf = gpd.read_file(datapath)
+```
+
+```{code-cell} ipython3
+%matplotlib inline
+
+ax = gdf.plot(figsize=(10, 10))
+```
+
+The `GeoDataFrame` contains the boundary coordinates, as well as some other data such as estimated population.
+
+```{code-cell} ipython3
+gdf.head()
+```
+
+## Creating the style dictionary
+
+Now we generate time series data for each country.
+
+Data for different areas might be sampled at different times, and `TimeSliderChoropleth` can deal with that. This means that there is no need to resample the data, as long as the number of datapoints isn't too large for the browser to deal with.
+
+To simulate that data is sampled at different times we random sample data for `n_periods` rows of data and then pick without replacing `n_sample` of those rows.
+
+```{code-cell} ipython3
+import pandas as pd
+
+n_periods, n_sample = 48, 40
+
+assert n_sample < n_periods
+
+datetime_index = pd.date_range("2016-1-1", periods=n_periods, freq="M")
+dt_index_epochs = datetime_index.astype("int64") // 10 ** 9
+dt_index = dt_index_epochs.astype("U10")
+
+dt_index
+```
+
+```{code-cell} ipython3
+import numpy as np
+
+styledata = {}
+
+for country in gdf.index:
+ df = pd.DataFrame(
+ {
+ "color": np.random.normal(size=n_periods),
+ "opacity": np.random.normal(size=n_periods),
+ },
+ index=dt_index,
+ )
+ df = df.cumsum()
+ df.sample(n_sample, replace=False).sort_index()
+ styledata[country] = df
+```
+
+Note that the geodata and random sampled data is linked through the feature_id, which is the index of the `GeoDataFrame`.
+
+```{code-cell} ipython3
+gdf.loc[0]
+```
+
+```{code-cell} ipython3
+styledata.get(0).head()
+```
+
+We see that we generated two series of data for each country; one for color and one for opacity. Let's plot them to see what they look like.
+
+```{code-cell} ipython3
+ax = df.plot()
+```
+
+Looks random alright. We want to map the column named `color` to a hex color. To do this we use a normal colormap. To create the colormap, we calculate the maximum and minimum values over all the timeseries. We also need the max/min of the `opacity` column, so that we can map that column into a range [0,1].
+
+```{code-cell} ipython3
+max_color, min_color, max_opacity, min_opacity = 0, 0, 0, 0
+
+for country, data in styledata.items():
+ max_color = max(max_color, data["color"].max())
+ min_color = min(max_color, data["color"].min())
+ max_opacity = max(max_color, data["opacity"].max())
+ max_opacity = min(max_color, data["opacity"].max())
+```
+
+Define and apply colormaps:
+
+```{code-cell} ipython3
+from branca.colormap import linear
+
+cmap = linear.PuRd_09.scale(min_color, max_color)
+
+
+def norm(x):
+ return (x - x.min()) / (x.max() - x.min())
+
+
+for country, data in styledata.items():
+ data["color"] = data["color"].apply(cmap)
+ data["opacity"] = norm(data["opacity"])
+```
+
+```{code-cell} ipython3
+styledata.get(0).head()
+```
+
+Finally we use `pd.DataFrame.to_dict()` to convert each dataframe into a dictionary, and place each of these in a map from country id to data.
+
+```{code-cell} ipython3
+styledict = {
+ str(country): data.to_dict(orient="index") for country, data in styledata.items()
+}
+```
+
+## Creating the map
+
+```{code-cell} ipython3
+import folium
+from folium.plugins import TimeSliderChoropleth
+
+
+m = folium.Map([0, 0], tiles="Stamen Toner", zoom_start=2)
+
+TimeSliderChoropleth(
+ gdf.to_json(),
+ styledict=styledict,
+).add_to(m)
+
+m
+```
+
+### Initial timestamp
+
+By default the timeslider starts at the beginning. You can also select another timestamp to begin with using the `init_timestamp` parameter. Note that it expects an index to the list of timestamps. In this example we use `-1` to select the last timestamp.
+
+```{code-cell} ipython3
+m = folium.Map([0, 0], tiles="Stamen Toner", zoom_start=2)
+
+TimeSliderChoropleth(
+ gdf.to_json(),
+ styledict=styledict,
+ init_timestamp=-1,
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/timestamped_geojson.md b/docs/user_guide/plugins/timestamped_geojson.md
new file mode 100644
index 0000000000..d2fb0b9a9f
--- /dev/null
+++ b/docs/user_guide/plugins/timestamped_geojson.md
@@ -0,0 +1,206 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+import folium.plugins
+```
+
+## TimestampedGeoJson
+
+### Example 1
+
+```{code-cell} ipython3
+m = folium.Map(location=[35.68159659061569, 139.76451516151428], zoom_start=16)
+
+# Lon, Lat order.
+lines = [
+ {
+ "coordinates": [
+ [139.76451516151428, 35.68159659061569],
+ [139.75964426994324, 35.682590062684206],
+ ],
+ "dates": ["2017-06-02T00:00:00", "2017-06-02T00:10:00"],
+ "color": "red",
+ },
+ {
+ "coordinates": [
+ [139.75964426994324, 35.682590062684206],
+ [139.7575843334198, 35.679505030038506],
+ ],
+ "dates": ["2017-06-02T00:10:00", "2017-06-02T00:20:00"],
+ "color": "blue",
+ },
+ {
+ "coordinates": [
+ [139.7575843334198, 35.679505030038506],
+ [139.76337790489197, 35.678040905014065],
+ ],
+ "dates": ["2017-06-02T00:20:00", "2017-06-02T00:30:00"],
+ "color": "green",
+ "weight": 15,
+ },
+ {
+ "coordinates": [
+ [139.76337790489197, 35.678040905014065],
+ [139.76451516151428, 35.68159659061569],
+ ],
+ "dates": ["2017-06-02T00:30:00", "2017-06-02T00:40:00"],
+ "color": "#FFFFFF",
+ },
+]
+
+features = [
+ {
+ "type": "Feature",
+ "geometry": {
+ "type": "LineString",
+ "coordinates": line["coordinates"],
+ },
+ "properties": {
+ "times": line["dates"],
+ "style": {
+ "color": line["color"],
+ "weight": line["weight"] if "weight" in line else 5,
+ },
+ },
+ }
+ for line in lines
+]
+
+folium.plugins.TimestampedGeoJson(
+ {
+ "type": "FeatureCollection",
+ "features": features,
+ },
+ period="PT1M",
+ add_last_point=True,
+).add_to(m)
+
+m
+```
+
+### Example 2
+
+```{code-cell} ipython3
+table = """\
+
+
+ | Firstname |
+ Lastname |
+ Age |
+
+
+ | Jill |
+ Smith |
+ 50 |
+
+
+ | Eve |
+ Jackson |
+ 94 |
+
+
+"""
+
+points = [
+ {
+ "time": "2017-06-02",
+ "popup": "address1
",
+ "coordinates": [-2.548828, 51.467697],
+ },
+ {
+ "time": "2017-07-02",
+ "popup": "address2",
+ "coordinates": [-0.087891, 51.536086],
+ },
+ {
+ "time": "2017-08-02",
+ "popup": "address3",
+ "coordinates": [-6.240234, 53.383328],
+ },
+ {
+ "time": "2017-09-02",
+ "popup": "address4",
+ "coordinates": [-1.40625, 60.261617],
+ },
+ {"time": "2017-10-02", "popup": table, "coordinates": [-1.516113, 53.800651]},
+]
+
+features = [
+ {
+ "type": "Feature",
+ "geometry": {
+ "type": "Point",
+ "coordinates": point["coordinates"],
+ },
+ "properties": {
+ "time": point["time"],
+ "popup": point["popup"],
+ "id": "house",
+ "icon": "marker",
+ "iconstyle": {
+ "iconUrl": "https://leafletjs.com/examples/geojson/baseball-marker.png",
+ "iconSize": [20, 20],
+ },
+ },
+ }
+ for point in points
+]
+
+features.append(
+ {
+ "type": "Feature",
+ "geometry": {
+ "type": "LineString",
+ "coordinates": [
+ [-2.548828, 51.467697],
+ [-0.087891, 51.536086],
+ [-6.240234, 53.383328],
+ [-1.40625, 60.261617],
+ [-1.516113, 53.800651],
+ ],
+ },
+ "properties": {
+ "popup": "Current address",
+ "times": [
+ "2017-06-02",
+ "2017-07-02",
+ "2017-08-02",
+ "2017-09-02",
+ "2017-10-02",
+ ],
+ "icon": "circle",
+ "iconstyle": {
+ "fillColor": "green",
+ "fillOpacity": 0.6,
+ "stroke": "false",
+ "radius": 13,
+ },
+ "style": {"weight": 0},
+ "id": "man",
+ },
+ }
+)
+
+m = folium.Map(
+ location=[56.096555, -3.64746],
+ tiles="cartodbpositron",
+ zoom_start=5,
+)
+
+folium.plugins.TimestampedGeoJson(
+ {"type": "FeatureCollection", "features": features},
+ period="P1M",
+ add_last_point=True,
+ auto_play=False,
+ loop=False,
+ max_speed=1,
+ loop_button=True,
+ date_options="YYYY/MM/DD",
+ time_slider_drag_update=True,
+ duration="P2M",
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/plugins/vector_tiles.md b/docs/user_guide/plugins/vector_tiles.md
new file mode 100644
index 0000000000..53401ddebb
--- /dev/null
+++ b/docs/user_guide/plugins/vector_tiles.md
@@ -0,0 +1,158 @@
+# Vector tiles using VectorGridProtobuf
+
+```{code-cell} ipython3
+from folium.plugins import VectorGridProtobuf
+import folium
+```
+
+```{code-cell} ipython3
+styles = {
+ "water": {
+ "fill": True,
+ "weight": 1,
+ "fillColor": "#06cccc",
+ "color": "#06cccc",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "admin": {
+ "weight": 1,
+ "fillColor": "pink",
+ "color": "pink",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "waterway": {
+ "weight": 1,
+ "fillColor": "#2375e0",
+ "color": "#2375e0",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "landcover": {
+ "fill": True,
+ "weight": 1,
+ "fillColor": "#53e033",
+ "color": "#53e033",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "landuse": {
+ "fill": True,
+ "weight": 1,
+ "fillColor": "#e5b404",
+ "color": "#e5b404",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "park": {
+ "fill": True,
+ "weight": 1,
+ "fillColor": "#84ea5b",
+ "color": "#84ea5b",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "boundary": {
+ "weight": 1,
+ "fillColor": "#c545d3",
+ "color": "#c545d3",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "aeroway": {
+ "weight": 1,
+ "fillColor": "#51aeb5",
+ "color": "#51aeb5",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "building": {
+ "fill": True,
+ "weight": 1,
+ "fillColor": "#2b2b2b",
+ "color": "#2b2b2b",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "water_name": {
+ "weight": 1,
+ "fillColor": "#022c5b",
+ "color": "#022c5b",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "transportation_name": {
+ "weight": 1,
+ "fillColor": "#bc6b38",
+ "color": "#bc6b38",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "place": {
+ "weight": 1,
+ "fillColor": "#f20e93",
+ "color": "#f20e93",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "housenumber": {
+ "weight": 1,
+ "fillColor": "#ef4c8b",
+ "color": "#ef4c8b",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "poi": {
+ "weight": 1,
+ "fillColor": "#3bb50a",
+ "color": "#3bb50a",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+ "road": {
+ "weight": 1,
+ "fillColor": "#f2b648",
+ "color": "#f2b648",
+ "fillOpacity": 0.2,
+ "opacity": 0.4
+ },
+}
+```
+
+```{code-cell} ipython3
+vectorTileLayerStyles = {}
+vectorTileLayerStyles["aerodrome_label"] = []
+vectorTileLayerStyles["aeroway"] = []
+vectorTileLayerStyles["area_name"] = []
+vectorTileLayerStyles["boundary"] = styles["admin"]
+vectorTileLayerStyles["building"] = []
+vectorTileLayerStyles["building_ln"] = []
+vectorTileLayerStyles["construct"] = []
+vectorTileLayerStyles["contour_line"] = []
+vectorTileLayerStyles["landcover"] = styles["landcover"]
+vectorTileLayerStyles["landuse"] = styles["landuse"]
+vectorTileLayerStyles["mountain_peak"] = []
+vectorTileLayerStyles["park"] = styles["park"]
+vectorTileLayerStyles["place"] = []
+vectorTileLayerStyles["poi"] = []
+vectorTileLayerStyles["spot_elevation"] = []
+vectorTileLayerStyles["transportation"] = styles["road"]
+vectorTileLayerStyles["transportation_name"] = []
+vectorTileLayerStyles["water"] = styles["water"]
+vectorTileLayerStyles["waterway"] = styles["water"]
+vectorTileLayerStyles["water_name"] = []
+```
+
+```{code-cell} ipython3
+url = "https://vectortiles3.geo.admin.ch/tiles/ch.swisstopo.leichte-basiskarte.vt/v1.0.0/{z}/{x}/{y}.pbf"
+m = folium.Map(tiles=None, location=[46.8, 8.2], zoom_start=14)
+
+options = {
+ "vectorTileLayerStyles": vectorTileLayerStyles
+}
+
+VectorGridProtobuf(url, "folium_layer_name", options).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/raster_layers.rst b/docs/user_guide/raster_layers.rst
new file mode 100644
index 0000000000..8be966ef71
--- /dev/null
+++ b/docs/user_guide/raster_layers.rst
@@ -0,0 +1,10 @@
+Raster layers
+--------------
+
+.. toctree::
+ :maxdepth: 2
+
+ raster_layers/tiles
+ raster_layers/image_overlay
+ raster_layers/video_overlay
+ raster_layers/wms_tile_layer
diff --git a/docs/user_guide/raster_layers/image_overlay.md b/docs/user_guide/raster_layers/image_overlay.md
new file mode 100644
index 0000000000..9e469c6dd1
--- /dev/null
+++ b/docs/user_guide/raster_layers/image_overlay.md
@@ -0,0 +1,148 @@
+# ImageOverlay
+
+It may happen that you want to draw an image on you map. Here are example on how to do that.
+
+
+## Using an image from disk
+
+If you have a static image file on your disk, you can simply draw it on the map.
+
+```{code-cell} ipython3
+import os
+import folium
+
+m = folium.Map([37, 0], zoom_start=1, tiles="stamentoner")
+merc = os.path.join("data", "Mercator_projection_SW.png")
+
+
+if not os.path.isfile(merc):
+ print(f"Could not find {merc}")
+else:
+ img = folium.raster_layers.ImageOverlay(
+ name="Mercator projection SW",
+ image=merc,
+ bounds=[[-82, -180], [82, 180]],
+ opacity=0.6,
+ interactive=True,
+ cross_origin=False,
+ zindex=1,
+ )
+
+ folium.Popup("I am an image").add_to(img)
+
+ img.add_to(m)
+ folium.LayerControl().add_to(m)
+
+m
+```
+
+A few remarks:
+
+* Note that your image has to be in Mercator projection format.
+
+ The image we've used is based on https://en.wikipedia.org/wiki/File:Mercator_projection_SW.jpg ; that you can find in wikipedia's article on Mercator Projection (https://en.wikipedia.org/wiki/Mercator_projection).
+
+
+You can also provide simply URL. In this case, the image will not be embedded in folium's output.
+
+```{code-cell} ipython3
+m = folium.Map([37, 0], zoom_start=1, tiles="stamentoner")
+
+folium.raster_layers.ImageOverlay(
+ image="https://upload.wikimedia.org/wikipedia/commons/f/f4/Mercator_projection_SW.jpg",
+ name="I am a jpeg",
+ bounds=[[-82, -180], [82, 180]],
+ opacity=1,
+ interactive=False,
+ cross_origin=False,
+ zindex=1,
+ alt="Wikipedia File:Mercator projection SW.jpg",
+).add_to(m)
+
+folium.LayerControl().add_to(m)
+
+
+m
+```
+
+This works exactly the same way if you want to put a JPG instead of a PNG.
+
+
+## Creating an image with numpy
+
+Now you may wish to create your own image, based on another python computation.
+For this, you'll need to have numpy installed on your machine.
+
+Let's create an image to draw a rectangle in the bounds `[[0, -60], [60, 60]]`.
+
+```{code-cell} ipython3
+import numpy as np
+
+image = np.zeros((61, 61))
+image[0, :] = 1.0
+image[60, :] = 1.0
+image[:, 0] = 1.0
+image[:, 60] = 1.0
+```
+
+We can draw it on the map in using:
+
+```{code-cell} ipython3
+m = folium.Map([37, 0], zoom_start=2)
+
+folium.raster_layers.ImageOverlay(
+ image=image,
+ bounds=[[0, -60], [60, 60]],
+ colormap=lambda x: (1, 0, 0, x),
+).add_to(m)
+
+m
+```
+
+Note that you need to provide a colormap of the form `lambda x: (R,G,B,A)` where `R,G,B,A` are floats between 0 and 1.
+
+Now, let's try to add a line at latitude 45°, and add a polyline to verify it's well rendered. We'll need to specify `origin='lower` to inform folium that the first lines of the array are to be plotted at the bottom of the image (see `numpy.imshow`, it's the same principle).
+
+```{code-cell} ipython3
+import numpy as np
+
+image = np.zeros((61, 1))
+
+image[45, :] = 1.0
+
+
+m = folium.Map([37, 0], zoom_start=3)
+
+folium.raster_layers.ImageOverlay(
+ image=image,
+ bounds=[[0, -60], [60, 60]],
+ colormap=lambda x: (1, 0, 0, x),
+ origin="lower",
+).add_to(m)
+
+folium.PolyLine([[45, -60], [45, 60]]).add_to(m)
+
+m
+```
+
+But even with `origin='lower'`, the red line is not at the good latitude. This is due to Mercator projection used in Leaflet (and most other map systems).
+
+You can read wikipedia's article on Mercator Projection (https://en.wikipedia.org/wiki/Mercator_projection), or simply let folium do the job, in precising that you want the mercator stuff to be handled.
+
+```{code-cell} ipython3
+m = folium.Map([37, 0], zoom_start=3)
+
+folium.PolyLine([[45, -60], [45, 60]]).add_to(m)
+
+folium.raster_layers.ImageOverlay(
+ image=image,
+ bounds=[[0, -60], [60, 60]],
+ origin="lower",
+ colormap=lambda x: (1, 0, 0, x),
+ mercator_project=True,
+).add_to(m)
+
+m
+```
+
+This time, the lines are properly positioned (at the precision of the array).
diff --git a/docs/user_guide/raster_layers/tiles.md b/docs/user_guide/raster_layers/tiles.md
new file mode 100644
index 0000000000..bb65c89575
--- /dev/null
+++ b/docs/user_guide/raster_layers/tiles.md
@@ -0,0 +1,55 @@
+## Tiles
+
+### Built-in tilesets
+
+```{code-cell} ipython3
+import folium
+
+
+lon, lat = -38.625, -12.875
+
+zoom_start = 8
+```
+
+```{code-cell} ipython3
+folium.Map(location=[lat, lon], tiles="OpenStreetMap", zoom_start=zoom_start)
+```
+
+```{code-cell} ipython3
+folium.Map(location=[lat, lon], tiles="Stamen Terrain", zoom_start=zoom_start)
+```
+
+```{code-cell} ipython3
+folium.Map(location=[lat, lon], tiles="Stamen Toner", zoom_start=zoom_start)
+```
+
+```{code-cell} ipython3
+folium.Map(location=[lat, lon], tiles="Stamen Watercolor", zoom_start=zoom_start)
+```
+
+```{code-cell} ipython3
+folium.Map(location=[lat, lon], tiles="Cartodb Positron", zoom_start=zoom_start)
+```
+
+```{code-cell} ipython3
+folium.Map(location=[lat, lon], tiles="Cartodb dark_matter", zoom_start=zoom_start)
+```
+
+
+### Custom tiles
+
+```{code-cell} ipython3
+attr = (
+ '© OpenStreetMap '
+ 'contributors, © CartoDB'
+)
+tiles = "https://{s}.basemaps.cartocdn.com/light_nolabels/{z}/{x}/{y}.png"
+
+folium.Map(location=[lat, lon], tiles=tiles, attr=attr, zoom_start=zoom_start)
+```
+
+### Other tilesets
+
+For a list of many more tile providers go to https://leaflet-extras.github.io/leaflet-providers/preview/.
+
+You can also use the xyzservices package: https://github.com/geopandas/xyzservices.
diff --git a/docs/user_guide/raster_layers/video_overlay.md b/docs/user_guide/raster_layers/video_overlay.md
new file mode 100644
index 0000000000..38019f55d2
--- /dev/null
+++ b/docs/user_guide/raster_layers/video_overlay.md
@@ -0,0 +1,21 @@
+# VideoOverlay
+
+```{code-cell} ipython3
+import folium
+
+
+m = folium.Map(location=[22.5, -115], zoom_start=4)
+
+video = folium.raster_layers.VideoOverlay(
+ video_url="https://www.mapbox.com/bites/00188/patricia_nasa.webm",
+ bounds=[[32, -130], [13, -100]],
+ opacity=0.65,
+ attr="Video from patricia_nasa",
+ autoplay=True,
+ loop=False,
+)
+
+video.add_to(m)
+
+m
+```
diff --git a/docs/user_guide/raster_layers/wms_tile_layer.md b/docs/user_guide/raster_layers/wms_tile_layer.md
new file mode 100644
index 0000000000..25b547eb91
--- /dev/null
+++ b/docs/user_guide/raster_layers/wms_tile_layer.md
@@ -0,0 +1,27 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+# WmsTileLayer
+
+```{code-cell} ipython3
+m = folium.Map(location=[41, -70], zoom_start=5, tiles="cartodb positron")
+
+folium.WmsTileLayer(
+ url="https://mesonet.agron.iastate.edu/cgi-bin/wms/nexrad/n0r.cgi",
+ name="test",
+ fmt="image/png",
+ layers="nexrad-n0r-900913",
+ attr=u"Weather data © 2012 IEM Nexrad",
+ transparent=True,
+ overlay=True,
+ control=True,
+).add_to(m)
+
+folium.LayerControl().add_to(m)
+
+m
+```
diff --git a/docs/user_guide/ui_elements.rst b/docs/user_guide/ui_elements.rst
new file mode 100644
index 0000000000..55e02e809c
--- /dev/null
+++ b/docs/user_guide/ui_elements.rst
@@ -0,0 +1,10 @@
+UI elements
+--------------
+
+.. toctree::
+ :maxdepth: 1
+
+
+ ui_elements/layer_control
+ ui_elements/popups
+ ui_elements/icons
diff --git a/docs/user_guide/ui_elements/icons.md b/docs/user_guide/ui_elements/icons.md
new file mode 100644
index 0000000000..0d1f1aa57d
--- /dev/null
+++ b/docs/user_guide/ui_elements/icons.md
@@ -0,0 +1,56 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+# Icons
+
+## Rotate icons
+
+```{code-cell} ipython3
+m = folium.Map(location=[41, -71], zoom_start=4)
+
+kw = {"prefix": "fa", "color": "green", "icon": "arrow-up"}
+
+angle = 180
+icon = folium.Icon(angle=angle, **kw)
+folium.Marker(location=[41, -72], icon=icon, tooltip=str(angle)).add_to(m)
+
+angle = 45
+icon = folium.Icon(angle=angle, **kw)
+folium.Marker(location=[41, -75], icon=icon, tooltip=str(angle)).add_to(m)
+
+angle = 90
+icon = folium.Icon(angle=angle, **kw)
+folium.Marker([41, -78], icon=icon, tooltip=str(angle)).add_to(m)
+
+m
+```
+
+## Custom icon
+
+```{code-cell} ipython3
+m = folium.Map(location=[45.3288, -121.6625], zoom_start=12, tiles="Stamen Terrain")
+
+url = "https://leafletjs.com/examples/custom-icons/{}".format
+icon_image = url("leaf-red.png")
+shadow_image = url("leaf-shadow.png")
+
+icon = folium.CustomIcon(
+ icon_image,
+ icon_size=(38, 95),
+ icon_anchor=(22, 94),
+ shadow_image=shadow_image,
+ shadow_size=(50, 64),
+ shadow_anchor=(4, 62),
+ popup_anchor=(-3, -76),
+)
+
+folium.Marker(
+ location=[45.3288, -121.6625], icon=icon, popup="Mt. Hood Meadows"
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/ui_elements/layer_control.md b/docs/user_guide/ui_elements/layer_control.md
new file mode 100644
index 0000000000..2f495ee865
--- /dev/null
+++ b/docs/user_guide/ui_elements/layer_control.md
@@ -0,0 +1,60 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+## LayerControl
+
+Add a control to the map to show or hide layers.
+
+```{code-cell} ipython3
+m = folium.Map(tiles=None)
+
+folium.TileLayer("OpenStreetMap").add_to(m)
+folium.TileLayer("stamentoner", show=False).add_to(m)
+
+folium.LayerControl().add_to(m)
+
+m
+```
+
+### Common layer arguments
+
+Every layer element in Folium has a couple common arguments:
+
+- `name`: how the layer will be named in the layer control.
+- `overlay`: True if the layer is an overlay, False if the layer is a base layer.
+ - base layer: only one of them can be active at a time. Mostly used for tile layers.
+ - overlay: multiple can be active at the same time. Used for anything else than tile layers.
+- `control`: Whether the layer can be controlled in the layer control.
+- `show`: Whether the layer will be shown when opening the map.
+
+Next we'll give some examples using a `FeatureGroup`.
+
+### Remove from control
+
+```{code-cell} ipython3
+m = folium.Map()
+
+fg = folium.FeatureGroup(name="Icon collection", control=False).add_to(m)
+folium.Marker(location=(0, 0)).add_to(fg)
+
+folium.LayerControl().add_to(m)
+
+m
+```
+
+### Show manually
+
+```{code-cell} ipython3
+m = folium.Map()
+
+fg = folium.FeatureGroup(name="Icon collection", show=False).add_to(m)
+folium.Marker(location=(0, 0)).add_to(fg)
+
+folium.LayerControl().add_to(m)
+
+m
+```
diff --git a/docs/user_guide/ui_elements/popups.md b/docs/user_guide/ui_elements/popups.md
new file mode 100644
index 0000000000..7c98b641f9
--- /dev/null
+++ b/docs/user_guide/ui_elements/popups.md
@@ -0,0 +1,231 @@
+# Popups
+
+## Simple popups
+
+You can define your popup at the feature creation, but you can also overwrite them afterwards:
+
+```{code-cell} ipython3
+import folium
+
+
+m = folium.Map([45, 0], zoom_start=4)
+
+folium.Marker([45, -30], popup="inline implicit popup").add_to(m)
+
+folium.CircleMarker(
+ location=[45, -10],
+ radius=25,
+ fill=True,
+ popup=folium.Popup("inline explicit Popup"),
+).add_to(m)
+
+ls = folium.PolyLine(
+ locations=[[43, 7], [43, 13], [47, 13], [47, 7], [43, 7]], color="red"
+)
+
+ls.add_child(folium.Popup("outline Popup on Polyline"))
+ls.add_to(m)
+
+gj = folium.GeoJson(
+ data={"type": "Polygon", "coordinates": [[[27, 43], [33, 43], [33, 47], [27, 47]]]}
+)
+
+gj.add_child(folium.Popup("outline Popup on GeoJSON"))
+gj.add_to(m)
+
+m
+```
+
+```{code-cell} ipython3
+m = folium.Map([45, 0], zoom_start=2)
+
+folium.Marker(
+ location=[45, -10],
+ popup=folium.Popup("Let's try quotes", parse_html=True, max_width=100),
+).add_to(m)
+
+folium.Marker(
+ location=[45, -30],
+ popup=folium.Popup(u"Ça c'est chouette", parse_html=True, max_width="100%"),
+).add_to(m)
+
+m
+```
+
+## HTML in popup
+
+```{code-cell} ipython3
+import branca
+
+m = folium.Map([43, -100], zoom_start=4)
+
+html = """
+ This is a big popup
+ With a few lines of code...
+
+
+ from numpy import *
+ exp(-2*pi)
+
+
+ """
+
+
+folium.Marker([30, -100], popup=html).add_to(m)
+
+m
+```
+
+## Iframe in popup
+
+You can also put any HTML code inside a Popup, thaks to the `IFrame` object.
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+html = """
+ This popup is an Iframe
+ With a few lines of code...
+
+
+ from numpy import *
+ exp(-2*pi)
+
+
+ """
+
+iframe = branca.element.IFrame(html=html, width=500, height=300)
+popup = folium.Popup(iframe, max_width=500)
+
+folium.Marker([30, -100], popup=popup).add_to(m)
+
+m
+```
+
+```{code-cell} ipython3
+import pandas as pd
+
+df = pd.DataFrame(
+ data=[["apple", "oranges"], ["other", "stuff"]], columns=["cats", "dogs"]
+)
+
+m = folium.Map([43, -100], zoom_start=4)
+
+html = df.to_html(
+ classes="table table-striped table-hover table-condensed table-responsive"
+)
+
+popup = folium.Popup(html)
+
+folium.Marker([30, -100], popup=popup).add_to(m)
+
+m
+```
+
+Note that you can put another `Figure` into an `IFrame` ; this should let you do strange things...
+
+```{code-cell} ipython3
+# Let's create a Figure, with a map inside.
+f = branca.element.Figure()
+folium.Map([-25, 150], zoom_start=3).add_to(f)
+
+# Let's put the figure into an IFrame.
+iframe = branca.element.IFrame(width=500, height=300)
+f.add_to(iframe)
+
+# Let's put the IFrame in a Popup
+popup = folium.Popup(iframe, max_width=2650)
+
+# Let's create another map.
+m = folium.Map([43, -100], zoom_start=4)
+
+# Let's put the Popup on a marker, in the second map.
+folium.Marker([30, -100], popup=popup).add_to(m)
+
+# We get a map in a Popup. Not really useful, but powerful.
+m
+```
+
+
+## Vega chart in popup
+
+[Vega](https://vega.github.io/vega/) is a way to describe charts. You can embed
+a Vega chart in a popup using the `Vega` class.
+
+```{code-cell} ipython3
+import json
+
+import numpy as np
+import vincent
+
+multi_iter2 = {
+ "x": np.random.uniform(size=(100,)),
+ "y": np.random.uniform(size=(100,)),
+}
+scatter = vincent.Scatter(multi_iter2, iter_idx="x", height=100, width=200)
+data = json.loads(scatter.to_json())
+
+m = folium.Map([0, 0], zoom_start=1)
+marker = folium.Marker([0, 0]).add_to(m)
+popup = folium.Popup("Hello").add_to(marker)
+folium.Vega(data, width="100%", height="100%").add_to(popup)
+
+m
+```
+
+## Vega-Lite chart in popup
+
+[Vega-lite](https://vega.github.io/vega-lite/) is a higher-level version of Vega.
+Folium supports it as well in the `VegaLite` class.
+
+```{code-cell} ipython3
+from altair import Chart
+
+import vega_datasets
+
+# load built-in dataset as a pandas DataFrame
+cars = vega_datasets.data.cars()
+
+scatter = (
+ Chart(cars)
+ .mark_circle()
+ .encode(
+ x="Horsepower",
+ y="Miles_per_Gallon",
+ color="Origin",
+ )
+)
+
+vega_lite = folium.VegaLite(
+ scatter,
+ width="100%",
+ height="100%",
+)
+
+m = folium.Map(location=[-27.5717, -48.6256])
+
+marker = folium.Marker([-27.57, -48.62])
+
+popup = folium.Popup()
+
+vega_lite.add_to(popup)
+popup.add_to(marker)
+
+marker.add_to(m)
+
+m
+```
+
+## Lazy loading
+
+If whatever you are showing in the popup is slow or heavy to load and you have many popups, you may not want to render the popup contents immediately. There's an argument to prevent loading until the popup is opened.
+
+```{code-cell} ipython3
+m = folium.Map([43, -100], zoom_start=4)
+
+html = "{a resource that is heavy to load, such as an image}"
+
+folium.Marker([30, -100], popup=html, lazy=True).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/vector_layers.rst b/docs/user_guide/vector_layers.rst
new file mode 100644
index 0000000000..ddcea51551
--- /dev/null
+++ b/docs/user_guide/vector_layers.rst
@@ -0,0 +1,11 @@
+Vector layers
+--------------
+
+.. toctree::
+ :maxdepth: 1
+
+ vector_layers/circle_and_circle_marker
+ vector_layers/polyline
+ vector_layers/rectangle
+ vector_layers/polygon
+ vector_layers/colorline
diff --git a/docs/user_guide/vector_layers/circle_and_circle_marker.md b/docs/user_guide/vector_layers/circle_and_circle_marker.md
new file mode 100644
index 0000000000..3cb153c323
--- /dev/null
+++ b/docs/user_guide/vector_layers/circle_and_circle_marker.md
@@ -0,0 +1,51 @@
+## Circle and CircleMarker
+
+`CircleMarker` has a radius specified in pixels, while `Circle` is specified in meters.
+That means a `CircleMarker` will not change size on your screen when you zoom,
+while `Circle` will have a fixed position on the map.
+
+```{code-cell} ipython3
+import folium
+
+m = folium.Map(location=[-27.5717, -48.6256], zoom_start=9)
+
+radius = 50
+folium.CircleMarker(
+ location=[-27.55, -48.8],
+ radius=radius,
+ color="cornflowerblue",
+ stroke=False,
+ fill=True,
+ fill_opacity=0.6,
+ opacity=1,
+ popup="{} pixels".format(radius),
+ tooltip="I am in pixels",
+).add_to(m)
+
+radius = 25
+folium.CircleMarker(
+ location=[-27.35, -48.8],
+ radius=radius,
+ color="black",
+ weight=3,
+ fill=False,
+ fill_opacity=0.6,
+ opacity=1,
+).add_to(m)
+
+radius = 10000
+folium.Circle(
+ location=[-27.551667, -48.478889],
+ radius=radius,
+ color="black",
+ weight=1,
+ fill_opacity=0.6,
+ opacity=1,
+ fill_color="green",
+ fill=False, # gets overridden by fill_color
+ popup="{} meters".format(radius),
+ tooltip="I am in meters",
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/vector_layers/colorline.md b/docs/user_guide/vector_layers/colorline.md
new file mode 100644
index 0000000000..bf828d3bbf
--- /dev/null
+++ b/docs/user_guide/vector_layers/colorline.md
@@ -0,0 +1,26 @@
+### ColorLine
+
+```{code-cell} ipython3
+import numpy as np
+
+x = np.linspace(0, 2 * np.pi, 300)
+
+lats = 20 * np.cos(x)
+lons = 20 * np.sin(x)
+colors = np.sin(5 * x)
+```
+
+```{code-cell} ipython3
+import folium
+
+m = folium.Map([0, 0], zoom_start=3)
+
+color_line = folium.ColorLine(
+ positions=list(zip(lats, lons)),
+ colors=colors,
+ colormap=["y", "orange", "r"],
+ weight=10,
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/vector_layers/polygon.md b/docs/user_guide/vector_layers/polygon.md
new file mode 100644
index 0000000000..ce83b2dc01
--- /dev/null
+++ b/docs/user_guide/vector_layers/polygon.md
@@ -0,0 +1,87 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+## Polygon
+
+```{code-cell} ipython3
+m = folium.Map(location=[35.67, 139.78], zoom_start=13)
+
+locations = [
+ [35.6762, 139.7795],
+ [35.6718, 139.7831],
+ [35.6767, 139.7868],
+ [35.6795, 139.7824],
+ [35.6787, 139.7791],
+]
+
+folium.Polygon(
+ locations=locations,
+ color="blue",
+ weight=6,
+ fill_color="red",
+ fill_opacity=0.5,
+ fill=True,
+ popup="Tokyo, Japan",
+ tooltip="Click me!",
+).add_to(m)
+
+m
+```
+
+```{code-cell} ipython3
+locations = [
+ [
+ [7.577794326946673, 8.998503901433935],
+ [7.577851434795945, 8.998572430673164],
+ [7.577988491475764, 8.998652380403087],
+ [7.578105560723088, 8.998426807051544],
+ [7.577891409660878, 8.998289750371725],
+ [7.577794326946673, 8.998503901433935],
+ ],
+ [
+ [7.578139824893071, 8.999291979141560],
+ [7.578359687549607, 8.999414759083890],
+ [7.578456769364435, 8.999266281014116],
+ [7.578471046101925, 8.999197181604700],
+ [7.578247331649095, 8.999094883721964],
+ [7.578139824893071, 8.99929197914156],
+ ],
+ [
+ [7.577851730672876, 8.997811268775080],
+ [7.578012579816743, 8.997460464828633],
+ [7.577798113991832, 8.997311104523930],
+ [7.577667902951418, 8.997663440915119],
+ [7.577851730672876, 8.997811268775080],
+ ],
+ [
+ [7.578562417221803, 8.999551816663029],
+ [7.578688052511666, 8.999654609172921],
+ [7.578813688700849, 8.999443313458185],
+ [7.578670920426703, 8.999369073523950],
+ [7.578562417221803, 8.999551816663029],
+ ],
+ [
+ [7.577865711533433, 8.998252059784761],
+ [7.577989601239152, 8.998002756022402],
+ [7.577648754586391, 8.997784460884190],
+ [7.577545911714481, 8.998069316645683],
+ [7.577865711533433, 8.998252059784761],
+ ],
+]
+
+m = folium.Map(location=[7.577798113991832, 8.997311104523930], zoom_start=16)
+
+folium.Polygon(
+ locations=locations,
+ smooth_factor=2,
+ color="crimson",
+ no_clip=True,
+ tooltip="Hi there!",
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/vector_layers/polyline.md b/docs/user_guide/vector_layers/polyline.md
new file mode 100644
index 0000000000..1003e71a8c
--- /dev/null
+++ b/docs/user_guide/vector_layers/polyline.md
@@ -0,0 +1,174 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+# PolyLine
+
+```{code-cell} ipython3
+# Coordinates are 15 points on the great circle from Boston to San Francisco.
+coordinates = [
+ [42.3581, -71.0636],
+ [42.82995815, -74.78991444],
+ [43.17929819, -78.56603306],
+ [43.40320216, -82.37774519],
+ [43.49975489, -86.20965845],
+ [43.46811941, -90.04569087],
+ [43.30857071, -93.86961818],
+ [43.02248456, -97.66563267],
+ [42.61228259, -101.41886832],
+ [42.08133868, -105.11585198],
+ [41.4338549, -108.74485069],
+ [40.67471747, -112.29609954],
+ [39.8093434, -115.76190821],
+ [38.84352776, -119.13665678],
+ [37.7833, -122.4167],
+]
+
+# Create the map and add the line
+m = folium.Map(location=[41.9, -97.3], zoom_start=4)
+
+folium.PolyLine(
+ locations=coordinates,
+ color="#FF0000",
+ weight=5,
+ tooltip="From Boston to San Francisco",
+).add_to(m)
+
+m
+```
+
+## Smoothing
+
+PolyLine objects in Leaflet are smoothed by default. This removes points from
+the line, putting less load on the browser when drawing. The level of smoothing
+can be set with the `smooth_factor` argument.
+
+```{code-cell} ipython3
+m = folium.Map(location=[41.9, -97.3], zoom_start=4)
+
+folium.PolyLine(
+ smooth_factor=50,
+ locations=coordinates,
+ color="grey",
+ tooltip="Too much smoothing?",
+ weight=5,
+).add_to(m)
+
+m
+```
+
+## Crossing the date line
+
+Take notice how lines behave when they cross the date line.
+
+```{code-cell} ipython3
+lon = lat = 0
+zoom_start = 1
+
+m = folium.Map(location=[lat, lon], zoom_start=zoom_start)
+
+kw = {"opacity": 1.0, "weight": 6}
+folium.PolyLine(
+ locations=[(2, 179), (2, -179)],
+ tooltip="Wrong",
+ color="red",
+ line_cap="round",
+ **kw,
+).add_to(m)
+
+folium.PolyLine(
+ locations=[(-2, 179), (-2, 181)],
+ tooltip="Correct",
+ line_cap="butt",
+ color="blue",
+ **kw,
+).add_to(m)
+
+folium.PolyLine(
+ locations=[(-6, -179), (-6, 179)],
+ line_cap="square",
+ color="green",
+ tooltip="Correct",
+ **kw,
+).add_to(m)
+
+folium.PolyLine(
+ locations=[(12, -179), (12, 190)],
+ color="orange",
+ tooltip="Artifact?",
+ **kw,
+).add_to(m)
+
+m
+```
+
+## Multi-PolyLine
+
+You can create multiple polylines by passing multiple sets of coordinates
+to a single `PolyLine` object.
+
+```{code-cell} ipython3
+lat = +38.89399
+lon = -77.03659
+zoom_start = 17
+
+m = folium.Map(location=[lat, lon], tiles="stamen toner", zoom_start=zoom_start)
+
+kw = {"color": "red", "fill": True, "radius": 20}
+
+folium.CircleMarker([38.89415, -77.03738], **kw).add_to(m)
+folium.CircleMarker([38.89415, -77.03578], **kw).add_to(m)
+
+
+locations = [
+ [
+ (38.893596444352134, -77.03814983367920),
+ (38.893379333722040, -77.03792452812195),
+ ],
+ [
+ (38.893379333722040, -77.03792452812195),
+ (38.893162222428310, -77.03761339187622),
+ ],
+ [
+ (38.893162222428310, -77.03761339187622),
+ (38.893028615148424, -77.03731298446655),
+ ],
+ [
+ (38.893028615148424, -77.03731298446655),
+ (38.892920059048464, -77.03691601753235),
+ ],
+ [
+ (38.892920059048464, -77.03691601753235),
+ (38.892903358095296, -77.03637957572937),
+ ],
+ [
+ (38.892903358095296, -77.03637957572937),
+ (38.893011914220770, -77.03592896461487),
+ ],
+ [
+ (38.893011914220770, -77.03592896461487),
+ (38.893162222428310, -77.03549981117249),
+ ],
+ [
+ (38.893162222428310, -77.03549981117249),
+ (38.893404384982480, -77.03514575958252),
+ ],
+ [
+ (38.893404384982480, -77.03514575958252),
+ (38.893596444352134, -77.03496336936950),
+ ],
+]
+
+folium.PolyLine(
+ locations=locations,
+ color="orange",
+ weight=8,
+ opacity=1,
+ smooth_factor=0,
+).add_to(m)
+
+m
+```
diff --git a/docs/user_guide/vector_layers/rectangle.md b/docs/user_guide/vector_layers/rectangle.md
new file mode 100644
index 0000000000..08701fba19
--- /dev/null
+++ b/docs/user_guide/vector_layers/rectangle.md
@@ -0,0 +1,46 @@
+```{code-cell} ipython3
+---
+nbsphinx: hidden
+---
+import folium
+```
+
+## Rectangle
+
+```{code-cell} ipython3
+m = folium.Map(location=[35.685, 139.76], zoom_start=15)
+
+kw = {
+ "color": "blue",
+ "line_cap": "round",
+ "fill": True,
+ "fill_color": "red",
+ "weight": 5,
+ "popup": "Tokyo, Japan",
+ "tooltip": "Click me!",
+}
+
+folium.Rectangle(
+ bounds=[[35.681, 139.766], [35.691, 139.776]],
+ line_join="round",
+ dash_array="5, 5",
+ **kw,
+).add_to(m)
+
+dx = 0.012
+folium.Rectangle(
+ bounds=[[35.681, 139.766 - dx], [35.691, 139.776 - dx]],
+ line_join="mitter",
+ dash_array="5, 10",
+ **kw,
+).add_to(m)
+
+folium.Rectangle(
+ bounds=[[35.681, 139.766 - 2 * dx], [35.691, 139.7762 - 2 * dx]],
+ line_join="bevel",
+ dash_array="15, 10, 5, 10, 15",
+ **kw,
+).add_to(m)
+
+m
+```
diff --git a/folium/features.py b/folium/features.py
index 5792290dcb..c363223e3f 100644
--- a/folium/features.py
+++ b/folium/features.py
@@ -809,7 +809,7 @@ def render(self, **kwargs) -> None:
class GeoJsonStyleMapper:
"""Create dicts that map styling to GeoJson features.
- Used in the GeoJson class. Users don't have to call this class directly.
+ :meta private:
"""
def __init__(
@@ -1053,11 +1053,9 @@ def get_bounds(self) -> List[List[float]]:
class GeoJsonDetail(MacroElement):
+ """Base class for GeoJsonTooltip and GeoJsonPopup.
- """
- Base class for GeoJsonTooltip and GeoJsonPopup to inherit methods and
- template structure from. Not for direct usage.
-
+ :meta private:
"""
base_template = """
diff --git a/folium/plugins/__init__.py b/folium/plugins/__init__.py
index f4fc1e4db9..f4f168e2b4 100644
--- a/folium/plugins/__init__.py
+++ b/folium/plugins/__init__.py
@@ -1,10 +1,4 @@
-"""
-Folium plugins
---------------
-
-Wrap some of the most popular leaflet external plugins.
-
-"""
+"""Wrap some of the most popular leaflet external plugins."""
from folium.plugins.antpath import AntPath
from folium.plugins.beautify_icon import BeautifyIcon
diff --git a/folium/vector_layers.py b/folium/vector_layers.py
index ba170a82ab..6e03506101 100644
--- a/folium/vector_layers.py
+++ b/folium/vector_layers.py
@@ -124,7 +124,7 @@ def path_options(
class BaseMultiLocation(MacroElement):
"""Base class for vector classes with multiple coordinates.
- Not for direct consumption
+ :meta private:
"""
diff --git a/requirements-dev.txt b/requirements-dev.txt
index d329a0c0fa..61d92d3176 100644
--- a/requirements-dev.txt
+++ b/requirements-dev.txt
@@ -14,6 +14,7 @@ gpxpy
ipykernel
jenkspy
jupyter
+jupytext
matplotlib
mypy
nbconvert
@@ -24,6 +25,7 @@ pandas
pillow
pre-commit
pycodestyle
+pydata-sphinx-theme
pytest
scipy
selenium
diff --git a/tests/selenium/test_selenium.py b/tests/selenium/test_selenium.py
index 71bed88311..15429d3936 100644
--- a/tests/selenium/test_selenium.py
+++ b/tests/selenium/test_selenium.py
@@ -15,9 +15,8 @@
def find_notebooks():
"""Return a list of filenames of the example notebooks."""
path = os.path.dirname(__file__)
- pattern = os.path.join(path, "..", "..", "examples", "*.ipynb")
- files = glob.glob(pattern)
- files = [f for f in files if not f.endswith(".nbconvert.ipynb")]
+ pattern = os.path.join(path, "..", "..", "docs", "**", "*.md")
+ files = glob.glob(pattern, recursive=True)
if files:
return files
else:
@@ -41,19 +40,17 @@ def test_notebook(filepath, driver):
def get_notebook_html(filepath_notebook):
- """Store iframes from a notebook in html files, remove them when done."""
- # run the notebook to make sure the output is up-to-date
+ """Convert markdown to notebook to html files, remove them when done."""
subprocess.run(
[
- "jupyter",
- "nbconvert",
+ "jupytext",
"--to",
"notebook",
"--execute",
filepath_notebook,
]
)
- filepath_notebook = filepath_notebook.replace(".ipynb", ".nbconvert.ipynb")
+ filepath_notebook = filepath_notebook.replace(".md", ".ipynb")
html_exporter = nbconvert.HTMLExporter()
body, _ = html_exporter.from_filename(filepath_notebook)