Migrate from st.components.v1.html to st.iframe before 2026-06-01

[nicolasguelfi]

Context

Streamlit has deprecated st.components.v1.html with a removal deadline of 2026-06-01:

st.components.v1.html will be removed after 2026-06-01.
Please replace st.components.v1.html with st.iframe.

Impact

13 core library files use components.html() with ~18 direct calls:

File	Calls	Pattern
book.py	5	Search script injection
loading.py	3	Loading overlay (height=0)
bib_preview.py	1	Hover card JS (height=0)
marker.py	1	Floating nav widget (height=0)
auth.py	1	Keyboard listener (height=0)
mermaid.py	1	Diagram pan/zoom (height=N, scrolling)
plantuml.py	1	Diagram pan/zoom (height=N, scrolling)
tikz.py	1	Diagram pan/zoom (height=N, scrolling)
latex.py	1	LaTeX rendering (height=N, scrolling)
browser.py	1	Chrome banner (height=0)
export.py	1	Dual-render pipeline

Note: Files using st.html() for CSS injection (grid, list, zoom, container, etc.) are not affected.

Risk assessment — HIGH (8/10)

• Deadline: ~2 months away
• All StreamTeX apps break after 2026-06-01 if not migrated
• Users cannot workaround — calls are in library code
• Two critical patterns to validate:
  1. Zero-height iframes (height=0) for JS injection via parent.document
  2. scrolling parameter — not documented in st.iframe() API

New API: st.iframe()

st.iframe(
    src: str | Path,
    *,
    width: int | Literal["stretch", "content"] = "stretch",
    height: int | Literal["stretch", "content"] = "content",
    tab_index: int | None = None,
)

Key differences:

• Auto-detects input type (URL, Path, HTML string)
• New sizing modes: "stretch", "content"
• No explicit scrolling parameter (needs investigation)

Proposed solution

Create a centralized wrapper streamtex/_iframe.py:

def stx_iframe(html: str, *, height: int = 0, scrolling: bool = False):
    """Unified iframe injection — auto-selects API by Streamlit version."""
    if _USE_NEW_IFRAME:
        st.iframe(html, height=height)
    else:
        import streamlit.components.v1 as components
        components.html(html, height=height, scrolling=scrolling)

Then replace all components.html() calls across 13 files with stx_iframe().

Validation checklist

• Verify st.iframe(html_string, height=0) works for JS injection
• Verify parent.document access is preserved (iframe sandbox policy)
• Verify scrolling behavior for diagram viewers
• Identify exact Streamlit version introducing st.iframe()
• Implement _iframe.py wrapper
• Migrate all 13 files
• Test all features: markers, bib preview, loading, auth, diagrams
• Update minimum Streamlit version in pyproject.toml if needed
• Release patch version before 2026-06-01

Deadline

Must be completed before 2026-05-15 (2 weeks buffer before removal date).

---

📅 Reminder: checkpoint on 2026-04-20 to verify progress.

[nicolasguelfi]

Research update — 2026-04-06

Deep analysis of Streamlit source code (iframe.py, IFrame.proto, IFrame.tsx, IFrameUtil.ts) on the develop branch.

Scrolling — ✅ NOT a problem

st.iframe() hard-codes scrolling = True (line 367). No parameter exposed.

StreamTeX pattern	Old API	New API	Impact
Zero-height JS injection (height=0)	scrolling=False (default)	scrolling=True (forced)	None — invisible iframe, no visual difference
Diagram viewers (height=N)	scrolling=True (explicit)	scrolling=True (forced)	None — identical behavior

parent.document access — ✅ Preserved

Same IFrameProto, same frontend component (IFrame.tsx), same sandbox policy:

allow-scripts + allow-same-origin + allow-forms + allow-modals + allow-popups + allow-downloads

Streamlit source comment: "basically un-sandboxes us". All JS injection patterns will continue to work.

HTML string detection — ✅ Safe

st.iframe() auto-detects input type. The _is_file() function (line 48) returns False if the string contains <, so all HTML strings are correctly routed to srcdoc. This covers 100% of StreamTeX use cases.

Remaining unknown

• Exact Streamlit version introducing st.iframe() — not yet in public release notes. Need to monitor releases.

Updated checklist

• Verify st.iframe(html_string, height=0) works for JS injection → Yes, safe
• Verify parent.document access is preserved → Yes, same sandbox
• Verify scrolling behavior for diagram viewers → Yes, always True
• Identify exact Streamlit version introducing st.iframe()
• Implement _iframe.py wrapper
• Migrate all 13 files
• Test all features end-to-end
• Update minimum Streamlit version in pyproject.toml
• Release patch version before 2026-06-01

Sources: iframe.py · IFrame.proto · IFrame.tsx · IFrameUtil.ts