[spec] st.iframe - Embed content in an iframe#14373
Conversation
Co-Authored-By: Claude Opus 4.6 <[email protected]>
✅ Snyk checks have passed. No issues have been found so far.
💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse. |
Spec PR Validation✅ All checks passed! |
lukasmasuch
changed the title
st.iframe - Embed content in an iframe
There was a problem hiding this comment.
Pull request overview
Adds a product spec for a proposed new st.iframe command to embed URLs, HTML strings, or local HTML files via iframes, consolidating legacy st.components.v1.iframe + st.components.v1.html into a single API.
Changes:
- Introduces a full product spec describing the proposed
st.iframeAPI surface and behavior (input auto-detection, sizing, sandbox/permissions policy). - Documents migration guidance from
st.components.v1.*and lists alternatives/future work. - Adds examples and an implementation checklist.
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?s=60&v=4){kind=small}
|
@cursor review |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
- Fix HTML detection description (fallback, not "detected by leading <") - Reorder input detection: URL patterns checked before filesystem - Add Windows path handling to detection rules - Document srcdoc relative asset resolution limitations - Correct permissions policy to reflect existing permissive defaults - Add missing Mount import in Starlette example - Clarify metrics naming (new "iframe" vs legacy "_iframe"/"_html") Co-Authored-By: Claude Opus 4.6 <[email protected]>
Co-Authored-By: Claude Opus 4.6 <[email protected]>
Co-Authored-By: Claude Opus 4.6 <[email protected]>
Co-Authored-By: Claude Opus 4.6 <[email protected]>
There was a problem hiding this comment.
Generally LGTM! Agree that st.iframe is better than st.embed (I think with embed I'd think of embedding the app itself somewhere else).
My only point is whether we need the scrolling parameter – shouldn't this just work like st.container, where if it has fixed height and the content is longer, we automatically enable scrolling, otherwise not? I can't really see a use case for showing a very long page in a smaller iframe without enabling scrolling, or is there one? (If there is a use case for it, I'm also fine with including the scrolling parameter, but I think we'd need to think through the name so we make it congruent with possible vertical/horizontal scrolling options on st.container in the future).
| ``` | ||
|
|
||
| The `st.components.v1.iframe` and `st.components.v1.html` functions will remain available | ||
| but should be documented as legacy APIs with migration guidance pointing to `st.iframe`. |
There was a problem hiding this comment.
Does this mean we're officially deprecating them? I could go either way, but would be good to specify.
There was a problem hiding this comment.
Yeah, I think we should deprecate them 👍 but maybe start with a soft deprecation (log + docstring). I will update the spec
There was a problem hiding this comment.
Oh we could also think about softly deprecating st.components.v1.html then and tell people to use st.html instead.
| [#4659](https://github.com/streamlit/streamlit/issues/4659) requests automatic height | ||
| adjustment for external URLs. True auto-height remains out of scope because: |
There was a problem hiding this comment.
Nit: the issue is actually only about auto-sizing when the input is a HTML string, which already seems to be resolved with the proposal here.
|
|
||
| This would use CSS transforms to scale the iframe. Worth revisiting if demand grows. | ||
|
|
||
| ### Folder Serving |
There was a problem hiding this comment.
nit: this is not out of scope since it's already resolved ;)
There was a problem hiding this comment.
I think it would be pretty nice to just do st.iframe("path/to/a/folder") and it shows whatever static page is in there. But static serving and starlette already provide ways to do that, and there is also the st.serve idea which could play a role here.
If it's an external URL, we don't really know that. However, we could probably just always activate scrolling. But I'm not sure about the initial rationale for configuring scrolling as On a related note, if we remove scrolling, it wouldn't be a 1-1 drop-in replacement anymore API-wise... but that might be fine. |
Soft deprecation includes docstring warnings and log messages, with functions remaining fully functional. Co-Authored-By: Claude Opus 4.6 <[email protected]>
Co-Authored-By: Claude Opus 4.6 <[email protected]>
Co-Authored-By: Claude Opus 4.6 <[email protected]>
|
Ooooh, I wasn't even aware we had that
Yeah that sounds right to me. I guess this only shows scrollbars if the content is actually longer, right? Seems like for |
Co-Authored-By: Claude Opus 4.6 <[email protected]>
- Remove incorrect reference to #4659 (that's about HTML content, now addressed) - Update Related section to note #4659 is addressed by height="content" Co-Authored-By: Claude Opus 4.6 <[email protected]>
Move scrolling to out-of-scope since scrolling="auto" shows scrollbars only when content overflows. Users can use CSS to hide if needed. Co-Authored-By: Claude Opus 4.6 <[email protected]>
to be fair, |
jrieke
left a comment
jrieke
left a comment
There was a problem hiding this comment.
to be fair, st.html doesn't even have height
Haha, might be good to add at some point. Anyway, approved.
- HTML files (.html, .htm, .xhtml) continue to use srcdoc - Other files (PDF, images, SVG, etc.) uploaded to media storage - Browser's native viewers handle rendering - No file type allowlist - unsupported types trigger download Co-Authored-By: Claude Opus 4.6 <[email protected]>
- Add data: prefix to URL detection patterns - Add example showing data URL usage Co-Authored-By: Claude Opus 4.6 <[email protected]>
Implements st.iframe as specified in #14373, consolidating st.components.v1.iframe and st.components.v1.html into a single, discoverable command in the main namespace. Features: - Auto-detects input type: URL, Path object, existing file, or HTML string - Supports absolute URLs (http/https/data:), relative URLs (/app/static/...) - Embeds local HTML files via srcdoc, non-HTML files via media storage - Width/height parameters with "stretch", "content", and pixel values - tab_index parameter for accessibility/keyboard navigation Closes #12977 Co-Authored-By: Claude Opus 4.6 <[email protected]>
## Describe your changes Implements `st.iframe` as specified in [#14373](#14373), consolidating `st.components.v1.iframe` and `st.components.v1.html` into a single, discoverable command in the main Streamlit namespace. **Features:** - Auto-detects input type: URL, Path object, existing file, or HTML string - Supports absolute URLs (`http://`, `https://`, `data:`), relative URLs (`/app/static/...`) - Embeds local HTML files via `srcdoc`, non-HTML files via media storage - `width`/`height` parameters with `"stretch"`, `"content"`, and pixel values - `height="content"` auto-sizes to content for srcdoc (falls back to 400px for URLs) - `width="content"` auto-sizes to content for srcdoc (falls back to stretch for URLs) - Uses standard `widthConfig`/`heightConfig` layout system (no custom proto fields) - `tab_index` parameter for accessibility/keyboard navigation **Usage:** ```python import streamlit as st from pathlib import Path # Embed a URL st.iframe("https://docs.streamlit.io", height=600) # Embed HTML content with auto-sizing st.iframe("<h1>Hello World</h1>") # height="content" by default # Embed a local HTML file st.iframe(Path("reports/dashboard.html"), height=800) # Embed a PDF st.iframe(Path("documents/manual.pdf"), height=600) # Auto-size both width and height st.iframe("<div style='width:200px'>Content</div>", width="content", height="content") ``` ## GitHub Issue Link (if applicable) - Closes #12977 ## Testing Plan - [x] Unit Tests (Python) - 42 tests covering URL handling, HTML string detection, local file handling, dimension parameters, tab_index validation, width/height content sizing - [x] Unit Tests (Frontend) - 27 tests covering rendering, auto-sizing behavior, message validation - [x] E2E Tests (Playwright) - 10 tests covering rendering, content verification, sandbox policy, auto-sizing - [x] Typing Tests (mypy) - Parameter and return type validation <!-- agent-metrics-start --> <details> <summary>Agent metrics</summary> | Type | Name | Count | |------|------|------:| | skill | checking-changes | 6 | | skill | debugging-streamlit | 1 | | skill | finalizing-pr | 3 | | skill | fixing-pr | 2 | | skill | implementing-feature | 1 | | skill | updating-internal-docs | 4 | | subagent | fixing-pr | 6 | | subagent | general-purpose | 19 | | subagent | reviewing-local-changes | 4 | | subagent | simplifying-local-changes | 4 | </details> <!-- agent-metrics-end --> --------- Co-authored-by: Claude Opus 4.6 <[email protected]> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Streamlit Bot <[email protected]>
Describe your changes
Spec renderer: https://issues.streamlit.app/spec_renderer?pr=14373
Product spec for
st.iframe— a new command to embed URLs, HTML content, or local HTML files in an iframe. Consolidatesst.components.v1.iframeandst.components.v1.htmlinto a single, discoverable API.Key design decisions:
srcparameter with auto-detection (URL vs HTML vs file path)height="content"default with fallback to 400px for cross-origin URLsfullscreenpermission enabled by defaultGitHub Issue Link (if applicable)
st.iframecommand #12977Contribution License Agreement
By submitting this pull request you agree that all contributions to this project are made under the Apache 2.0 license.