+
+
streamlit-folium vs streamlit-folium-vnext
+
A complete comparison of how the two packages work — from Python API to frontend rendering
+
+
+
1. The Core Difference in One Sentence
+
+
+ The old package lets folium render the map — Python hands the frontend a blob of Leaflet JavaScript and the frontend executes it.
+ The new package lets the frontend render the map — Python extracts structured data and the frontend reconstructs Leaflet objects from that data.
+
+
+
+ Old: Python → folium Jinja2 templates → raw HTML + raw JS strings → eval() in browser
+ New: Python → CompilerRegistry → typed MapSpec data tree → frontend registry dispatch → Leaflet API calls
+
+
+
+
2. Components v1 vs Components v2
+
+
+ The packages use entirely different Streamlit component APIs. This is not just an implementation detail —
+ the move from CCv1 to CCv2 is what makes most of the other improvements possible.
+
+
+
+
+
Old — streamlit.components.v1
+
+# Python: register by URL or build path
+import streamlit.components.v1 as components
+
+_component_func = components.declare_component(
+ "st_folium",
+ url="http://localhost:3001", # dev
+ # path=build_dir # prod
+)
+
+# Call site: pass args as flat kwargs
+_component_func(
+ script=leaflet_js_string,
+ html=html_string,
+ js_links=cdn_url_list,
+ plugins=plugin_dicts,
+ returned_objects=["last_clicked"],
+ ...
+)
+
+
+
+
New — streamlit.components.v2
+
+# Python: JS bundle inlined — no server needed
+import streamlit.components.v2 as components_v2
+
+_component = components_v2.component(
+ "st_folium_vnext",
+ js=_JS_CODE, # bundle read from disk
+ html=" ",
+ isolate_styles=False,
+)
+
+# Call site: data + per-key callbacks
+_component(
+ key=key,
+ data={"spec": spec_dict, "height": height},
+ default={"center": None, "zoom": None, ...},
+ on_center_change=_noop,
+ on_zoom_change=_noop,
+ on_bounds_change=_noop,
+ on_event_change=_noop,
+)
+
+
+
+
+
How the frontend is structured
+
+
+
+
Old — event listener in an iframe
+
+ The frontend is a React app served from a separate dev server or build directory.
+ Streamlit embeds it in an <iframe>. The app registers a listener
+ for RENDER_EVENT and calls Streamlit.setComponentValue()
+ to send data back. Frame height is managed manually.
+
+
+// Must call these explicitly
+Streamlit.events.addEventListener(
+ Streamlit.RENDER_EVENT, onRender
+)
+Streamlit.setComponentReady()
+Streamlit.setFrameHeight()
+
+// To send state back to Python
+Streamlit.setComponentValue({ last_clicked: ..., zoom: ... })
+
+
+
+
New — renderer function, no iframe
+
+ The frontend is a single exported function. Streamlit calls it directly and passes a
+ parentElement DOM node (inside the Streamlit page itself — no iframe).
+ State is sent back per-key via setStateValue / setTriggerValue.
+ No manual setup or frame sizing required.
+
+
+// The entire frontend is this one function
+const StFoliumVnext: FrontendRenderer<ComponentState, ComponentData>
+ = ({ parentElement, data, setStateValue, setTriggerValue }) => {
+
+ // parentElement is a real DOM node in the page
+ // Build the Leaflet map inside it...
+
+ // Send state back per key
+ setStateValue("center", [lat, lng])
+ setStateValue("zoom", zoom)
+ setTriggerValue("event", { type: "click", ... })
+
+ return () => {} // optional cleanup on unmount
+}
+
+export default StFoliumVnext
+
+
+
+
+
setStateValue vs setTriggerValue vs setComponentValue
+
+
+ | Concept | CCv1 | CCv2 |
|---|
+
+ | How state is sent to Python | One call: Streamlit.setComponentValue({...}) — a single flat dict | Per-key: setStateValue(key, val) / setTriggerValue(key, val) |
+ | State persistence across reruns | No — rebuilt from scratch each time | setStateValue values persist; setTriggerValue resets to null after one rerun |
+ | Python callbacks | Single default= dict; no per-key callbacks | on_<key>_change= callback per state key |
+ | Component isolation | Full iframe — styles and globals cannot leak either way | No iframe — shares the page DOM; isolate_styles=False allows Leaflet CSS to work correctly |
+ | JS delivery | Served from a URL (dev server or path=) | Bundle read from disk and inlined via js=_JS_CODE |
+
+
+
+
Why no iframe is the key enabler
+
+
+ The CCv1 iframe persists across reruns as long as key= doesn't change, which is
+ how the old package achieves partial incremental updates at all — window.map stays
+ alive. But because all layer state is tracked through window globals written by
+ eval'd strings, only feature_group and layer_control can be swapped.
+ In CCv2, parentElement is equally stable, but the instances Map tracks
+ every layer by a stable typed ID — so syncLayers() can diff any layer type cleanly,
+ without globals, eval, or re-hooking listeners.
+
+
+
+ Chain of enablement: CCv2 persistent parentElement
+ → instances Map survives reruns
+ → syncLayers() can diff against live Leaflet objects
+ → incremental layer updates without rebuilding the map
+
+
+
+
3. What Python Sends to the Frontend
+
+
The most visible difference is the shape of the payload that crosses the Python/JS boundary.
+
+
+
+
Old — streamlit_folium
+
Raw strings from folium's Jinja2 render pipeline:
+
+MapSpec(
+ html = "<div class='folium-map' ...>",
+ header = "<link rel=stylesheet ...>...",
+ script = "var map_div = L.map('map_div', {...}); ...",
+ map_id = "map_5f9d46...",
+ assets = AssetSpec(
+ js = ["https://cdnjs.../leaflet.js", ...],
+ css = ["https://cdnjs.../leaflet.css", ...],
+ ),
+ plugins = [
+ PluginSpec(
+ kind = "feature_group",
+ script = "var feature_group_feature_group_0 = ...",
+ ),
+ ],
+)
+
+
+
+
New — streamlit_folium_vnext
+
Structured data tree — no JavaScript anywhere:
+
+MapSpec(
+ version = 1,
+ map = {"id": "map-0", "center": [45.5, -122.6],
+ "zoom": 12, "options": {...}},
+ layers = [
+ MapNode(kind="tile_layer", id="tile-layer-0",
+ props={"url": "https://tile.openstreetmap..."}),
+ MapNode(kind="marker", id="marker-1",
+ props={"location": [45.5, -122.6], ...}),
+ ],
+ controls = [...],
+ plugins = [
+ MapNode(kind="marker_cluster", id="marker-cluster-2",
+ props={"markers": [...]}),
+ ],
+ subscriptions = ["last_clicked"],
+)
+
+
+
+
+
+ The old PluginSpec.script field contains a raw JavaScript string — it is the literal output of calling folium_object.render(),
+ which runs folium's internal Jinja2 templates. The new MapNode.props is a plain Python dict
+ of typed values. No JavaScript is ever generated in Python.
+
+
+
+
4. How Python Builds the Payload
+
+
+
+
Old — render pipeline
+
+# 1. Let folium render itself to JS strings
+html = fig.get_root().html.render()
+header = fig.get_root().header.render()
+script = generate_leaflet_string(fig)
+
+# 2. Scrape CDN URLs by walking the element tree
+for elem in walk(folium_map):
+ css_links.extend(elem.default_css)
+ js_links.extend(elem.default_js)
+
+# 3. Render plugin JS strings via Jinja2
+feature_group.render()
+script_str = generate_leaflet_string(feature_group)
+plugins.append(PluginSpec(kind="feature_group",
+ script=script_str))
+
+
+
+
New — compiler pipeline
+
+# 1. Walk the folium object tree
+for child in obj._children.values():
+
+ # 2. Look up a compile function by Python type
+ handler = registry.resolve(child)
+
+ # 3. Extract structured data — no JS generated
+ node = handler(child, context)
+
+ # 4. Route by kind into the right bucket
+ match node.kind:
+ case "marker" | "geojson" | ...:
+ spec.layers.append(node)
+ case "layer_control":
+ spec.controls.append(node)
+ case _:
+ spec.plugins.append(node)
+
+
+
+
+
+ In the old version Python is a pass-through — it calls folium's render methods and relays the
+ resulting JS strings. In the new version Python is a compiler — it reads folium object attributes
+ and emits a data representation.
+
+
+
+
5. How the Frontend Initializes the Map
+
+
+
+
Old — script injection + eval
+
+// 1. Inject CDN <script> tags sequentially
+for (const link of js_links) {
+ await new Promise((resolve, reject) => {
+ const s = document.createElement("script")
+ s.src = link
+ s.onload = resolve; s.onerror = reject
+ document.body.appendChild(s)
+ })
+}
+
+// 2. Inject folium HTML into DOM
+html_div.innerHTML = html
+document.body.appendChild(html_div)
+
+// 3. Eval the entire rendered Leaflet script
+render_script.innerHTML =
+ script +
+ `window.map = map_div;
+ window.initComponent(map_div, ...);`
+document.body.appendChild(render_script)
+
+
+
+
New — registry dispatch
+
+// 1. Load all needed CDN deps in parallel
+await collectDeps(spec) // Promise.all
+
+// 2. Create the Leaflet map from spec data
+const map = L.map(container, camelizeKeys(spec.map.options))
+map.setView(spec.map.center, spec.map.zoom)
+
+// 3. Render each layer via registry lookup
+for (const node of spec.layers) {
+ const fn = layerRenderers.get(node.kind)
+ if (fn) fn(map, node, setTrigger)
+}
+
+// 4. Mount controls and plugins via registries
+for (const node of spec.controls) {
+ controlMounters.get(node.kind)?.(map, node)
+}
+for (const node of spec.plugins) {
+ pluginMounters.get(node.kind)?.(map, node, setTrigger)
+}
+
+
+
+
+
+ eval() in the old package — on plugin re-renders (e.g. when a new feature_group is passed) the old frontend
+ literally calls eval(feature_group + layer_control) with the raw JavaScript strings sent from Python.
+ The new package never evaluates strings — it calls Leaflet's API directly.
+
+
+
+
6. CDN Loading
+
+
+ The old and new packages solve the "load extra CDN libraries for plugins" problem in completely different places.
+
+
+
+
+
Old — Python scrapes, frontend loads sequentially
+
+# Python: walk element tree, collect URLs
+for elem in walk(folium_map):
+ css_links.extend(
+ href for _, href in elem.default_css
+ )
+ js_links.extend(
+ src for _, src in elem.default_js
+ )
+assets = AssetSpec(js=js_links, css=css_links)
+
+
+// Frontend: inject each <script> sequentially
+for (const link of js_links) {
+ await new Promise(...) // one at a time
+}
+
+
+
+
New — TypeScript owns all CDN knowledge
+
+// TypeScript: each plugin kind declares its CDN deps
+pluginDeps.set("marker_cluster", () =>
+ ensureDep("leaflet-markercluster", async () => {
+ await loadStylesheet("sl-mc-css",
+ "https://unpkg.com/leaflet.markercluster@1.5.3/...")
+ if (!L?.MarkerClusterGroup)
+ await loadScript("https://unpkg.com/.../leaflet.markercluster.js")
+ })
+)
+
+// All plugins' deps fanned out in parallel
+function collectDeps(spec): Promise<void> {
+ const loads = spec.plugins
+ .map(p => pluginDeps.get(p.kind)?.())
+ .filter(Boolean)
+ return Promise.all(loads)
+}
+
+
+
+
+
+ | Concern | Old | New |
|---|
+
+ | Where CDN URLs live | Inside folium/branca Python objects (default_js, default_css) | In TypeScript pluginDeps Map |
+ | Who controls loading order | Python (sends ordered list); frontend loads serially | Frontend; all needed deps loaded in parallel via Promise.all |
+ | Deduplication when two maps use same plugin | Not handled — same URL injected twice | ensureDep(key, ...) memoises by string key |
+ | Adding a CDN dep for a new plugin | Must add to folium object's default_js / default_css (inside folium library, not this package) | One pluginDeps.set("kind", ...) call in index.ts |
+
+
+
+
+
7. Re-renders and Layer Updates
+
+
+ When Streamlit sends a new render event (e.g. a Python slider changed the data), the two packages behave very differently.
+
+
+
+
+
Old — partial incremental updates, hackily
+
+ The base map (tile layer, markers, GeoJSON baked into the initial script) is rendered once
+ at init and can never be updated. However, feature_group and layer_control
+ plugins can be swapped between reruns — via a fragile mechanism using window
+ globals, JSON.stringify diffing, and eval().
+
+
+// On every RENDER_EVENT, finalizeOnRender() runs:
+
+// 1. Detect change via full JSON.stringify diff
+if (JSON.stringify(plugins) !==
+ JSON.stringify(window.__GLOBAL_DATA__.last_feature_group)) {
+
+ // 2. Remove old layers via window.feature_group global
+ window.feature_group.forEach((layer: Layer) => {
+ window.map.removeLayer(layer)
+ })
+ window.map.removeControl(window.layer_control)
+
+ // 3. Re-add by eval()ing the new raw JS strings
+ // eslint-disable-next-line
+ eval(feature_group + layer_control)
+
+ // 4. Re-hook all click listeners on every layer
+ for (let key in window.map._layers) {
+ window.map._layers[key].on("click", onLayerClick)
+ }
+}
+
+
+ This only works because the CCv1 iframe persists across Python reruns as long as the
+ key= parameter doesn't change — keeping window.map alive.
+ But it relies on three side-channel globals (window.map, window.feature_group,
+ window.layer_control) written by the eval'd JS strings, and re-hooks
+ click listeners on every layer on every update.
+
+
+
+
New — incremental diffing via syncLayers()
+
+ Every MapInstance holds a layerRefs: Map<string, any> keyed by stable node IDs.
+ On every render event, syncLayers() computes the diff: IDs no longer in the spec are
+ removed from the Leaflet map; new IDs are created and added. Only the changed layers are touched.
+ Works for all layer types, not just feature groups.
+
+
+
+
+
+// New — syncLayers() incremental diff
+function syncLayers(instance: MapInstance, spec: MapSpec, setTrigger: SetTrigger) {
+ const { map, layerRefs } = instance
+ const nextIds = new Set(spec.layers.map(n => n.id))
+
+ // Remove layers that are no longer in the spec
+ for (const [id, layer] of layerRefs) {
+ if (!nextIds.has(id)) { map.removeLayer(layer); layerRefs.delete(id) }
+ }
+
+ // Add layers that are new
+ for (const node of spec.layers) {
+ if (layerRefs.has(node.id)) continue // already present
+ const fn = layerRenderers.get(node.kind)
+ if (fn) layerRefs.set(node.id, fn(map, node, setTrigger))
+ }
+}
+
+
+
+
8. Events and Return Values
+
+
+
+
Old — window globals + string keys
+
+ All event state lives in window.__GLOBAL_DATA__. Click/move/draw handlers write directly
+ into named fields. The user specifies which fields to return via the returned_objects
+ argument (a list of strings). The frontend filters __GLOBAL_DATA__ to only those keys
+ before calling Streamlit.setComponentValue().
+
+
+// 27 fields in window.__GLOBAL_DATA__
+global_data.lat_lng_clicked = e.latlng
+global_data.last_object_clicked = e.latlng
+global_data.last_object_clicked_tooltip = ...
+global_data.all_drawings = ...
+// ...etc
+
+
+
+
New — typed subscriptions
+
+ The Python compiler specifies which events to subscribe to via MapSpec.subscriptions.
+ The frontend only tracks and returns the subscribed fields. Event state is held in a typed
+ ComponentState interface rather than a catch-all global object.
+
+
+// Python side — explicit subscription
+spec = compile_folium_map(m,
+ subscribe=["last_clicked", "bounds"])
+
+// Frontend — typed state
+interface ComponentState {
+ center: [number, number] | null
+ zoom: number | null
+ bounds: [[number, number], [number, number]] | null
+ event: unknown
+}
+
+
+
+
+
+
9. Case Study: Marker Cluster
+
+
+ Marker cluster is a good end-to-end example because it requires a CDN library, has nested children
+ (individual markers), and fires click events.
+
+
+
+
+
Old — folium renders everything
+
+# Python does nothing special for MarkerCluster.
+# folium's own Jinja2 template renders it to JS:
+#
+# var marker_cluster_abc123 =
+# L.markerClusterGroup({...});
+# var marker_xyz = L.marker([45.5, -122.6])
+# .addTo(marker_cluster_abc123);
+# marker_cluster_abc123.addTo(map_div);
+#
+# That JS string is included in the main
+# 'script' payload field and eval()d at init.
+#
+# CDN URL scraped from:
+# MarkerCluster.default_js (inside folium)
+
+
+
+
New — two explicit registration points
+
+# Python: extract data from folium object
+def compile_marker_cluster(obj, context):
+ markers = []
+ for child in obj._children.values():
+ markers.append({
+ "location": list(child.location),
+ "tooltip": tooltip_text,
+ "popup": popup_html,
+ })
+ return make_node("marker_cluster",
+ context.allocate_id("marker-cluster"),
+ markers=markers,
+ options=dict(obj.options),
+ )
+
+registry.register(
+ folium.plugins.MarkerCluster,
+ compile_marker_cluster,
+)
+
+
+// TypeScript: CDN dep registration
+pluginDeps.set("marker_cluster", () =>
+ ensureDep("leaflet-markercluster", async () => {
+ await loadStylesheet("sl-mc-css", "...")
+ if (!L?.MarkerClusterGroup)
+ await loadScript("...leaflet.markercluster.js")
+ })
+)
+
+// TypeScript: render registration
+layerRenderers.set("marker_cluster", renderMarkerCluster)
+
+function renderMarkerCluster(map, node, setTrigger) {
+ const group = L.markerClusterGroup()
+ for (const m of node.props.markers) {
+ const marker = L.marker(m.location)
+ // attach tooltip, popup, click handler...
+ group.addLayer(marker)
+ }
+ return group.addTo(map)
+}
+
+
+
+
+
+
10. Adding Support for a New Folium Object
+
+
+
+
+ | Step |
+ Old |
+ New |
+
+
+
+
+ | Write Python data extractor |
+ Not needed — folium renders it to JS itself via Jinja2. No Python code to write. |
+ Write a compile_*(obj, context) → MapNode function in compiler/plugins/ |
+
+
+ | Register the Python type |
+ Not applicable |
+ registry.register(folium.plugins.MyType, compile_my_type) in compile_map.py |
+
+
+ | CDN dependency |
+ Must add default_js / default_css to the folium object class (inside the folium library — not this package) |
+ pluginDeps.set("my_kind", () => ensureDep(...)) in index.ts |
+
+
+ | Write frontend renderer |
+ Not needed — folium's rendered JS is executed directly |
+ Write a renderMyKind(map, node, setTrigger) function in index.ts |
+
+
+ | Register the frontend renderer |
+ Not applicable |
+ layerRenderers.set("my_kind", renderMyKind) or pluginMounters.set(...) |
+
+
+ | Files touched total |
+ 0 files in this package (folium does everything) |
+ 2 files: compile_map.py + compiler/plugins/*.py (Python) and index.ts (TypeScript) |
+
+
+
+
+
+ The old package's "zero files" advantage is actually a constraint: you can only support what folium
+ already knows how to render via Jinja2. The new package requires more explicit work per type but gives
+ full control over the rendering, event handling, and CDN loading of each object.
+
+
+
+
11. Full Architecture Comparison
+
+
Old package data flow
+
+ Python (st_folium)
+ │
+ ├─ folium.Map._children ──► folium Jinja2 templates ──► raw JS strings
+ ├─ branca element tree ──► scrape default_js/css ──► CDN URL lists
+ │
+ └─ MapSpec { html, header, script, assets{js,css}, plugins[{kind, script}] }
+ │
+ │ (Streamlit component iframe)
+ ▼
+ Frontend (index.tsx)
+ │
+ ├─ inject <script src=cdnUrl> for each URL in js_links (sequentially)
+ ├─ inject HTML string into DOM
+ ├─ eval(script) ──► Leaflet map created, all layers/markers/plugins added
+ ├─ window.map = map_div
+ ├─ initComponent() ──► walk map._layers, attach click/draw/move handlers
+ │
+ └─ On re-render: JSON.stringify(plugins) diff → if changed: removeLayer(window.feature_group),
+ removeControl(window.layer_control), eval(new_feature_group_script + new_layer_control_script),
+ re-hook click listeners on all layers. Base map layers unchanged.
+
+
+
New package data flow
+
+ Python (st_folium_vnext)
+ │
+ ├─ folium.Map._children ──► CompilerRegistry.resolve(type) ──► compile_fn
+ │ │
+ │ ▼
+ │ MapNode{kind,id,props}
+ │
+ └─ MapSpec { map{center,zoom}, layers[], controls[], plugins[], subscriptions[] }
+ │
+ │ (Streamlit component iframe — pure JSON, no JS)
+ ▼
+ Frontend (index.ts)
+ │
+ ├─ collectDeps(spec)
+ │ └─ for each plugin kind: pluginDeps.get(kind)?.()
+ │ └─ ensureDep(key, loader) ──► Promise.all (parallel CDN loading)
+ │
+ ├─ L.map(container, options).setView(center, zoom)
+ │
+ ├─ for each layer node: layerRenderers.get(kind)(map, node, setTrigger)
+ ├─ for each control node: controlMounters.get(kind)(map, node)
+ ├─ for each plugin node: pluginMounters.get(kind)(map, node, setTrigger)
+ │
+ └─ On re-render: syncLayers() ──► diff layerRefs Map, add/remove only changed nodes
+
+
+
+
+
12. Summary
+
+
+ | Property | streamlit-folium (old) | streamlit-folium-vnext (new) |
|---|
+
+ | Streamlit component API | components.v1.declare_component() — iframe-based, event listener, setComponentValue() | components.v2.component() — no iframe, inline JS, setStateValue() / setTriggerValue() |
+ | What Python sends | Raw HTML + JS strings from folium's Jinja2 render | Structured MapSpec data tree — no JavaScript |
+ | Who renders to Leaflet API | folium (in Python, via Jinja2) | The frontend TypeScript (via registry dispatch) |
+ | How scripts execute | eval() of the raw JS string | Direct Leaflet API calls from TypeScript |
+ | CDN loading | Python scrapes; frontend injects sequentially | TypeScript pluginDeps; loaded in parallel |
+ | Layer updates on re-render | feature_group and layer_control only — via JSON.stringify diff, eval(), and window globals. Base map layers are frozen. | syncLayers() stable-ID diff — any layer type, no globals, no eval |
+ | Event state | window.__GLOBAL_DATA__ with 27 string-keyed fields | Typed ComponentState; explicit subscriptions list |
+ | Support for a new type | Free — if folium supports it, it renders automatically | Requires a Python compiler + TypeScript renderer (2 files) |
+ | External extensibility | Not possible without forking | layerRenderers.set() / registry.register() from any module |
+
+
+
+