Docs for URL pages and navigation#14480
Conversation
|
Thanks for contributing to Streamlit! 🎈 Please make sure you have read our Contributing Guide. You can find additional information about Streamlit development in the wiki. The review process:
We're receiving many contributions and have limited review bandwidth — please expect some delay. We appreciate your patience! 🙏 |
✅ 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. |
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?s=60&v=4){kind=small}
There was a problem hiding this comment.
Pull request overview
This PR updates Streamlit’s public API documentation to better explain URL-defined pages and multipage navigation behavior, mainly by restructuring parameter descriptions into clearer bullet lists and refining the stated limitations around internal vs external pages.
Changes:
- Rewrites
st.Pagedocstring sections to clarify what constitutes a page source (callable, Python file, or external URL) and how visibility affects access. - Expands
st.page_linkandst.switch_pagedocstrings to more explicitly describe acceptablepageinputs forst.navigationvspages/directory apps. - Minor doc polish (e.g., capitalization of “URL”) and reformats the
st.Pageexample into an RSTcode-block.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 6 comments.
| File | Description |
|---|---|
lib/streamlit/navigation/page.py |
Refines st.Page docstring for page source types, visibility behavior, URL access note, and example formatting. |
lib/streamlit/elements/widgets/button.py |
Updates st.link_button and st.page_link docs, especially the page parameter semantics and URL-page behavior. |
lib/streamlit/commands/execution_control.py |
Updates st.switch_page docstring to clarify supported targets and st.navigation vs pages/ behavior. |
| - ``StreamlitPage``: The source of the ``StreamlitPage`` and its | ||
| ``url_path`` must match a page defined in ``st.navigation``. The | ||
| ``StreamlitPage`` must be internal and can't be defined by a URL. | ||
| Use ``st.Page`` to craete a ``StreamlitPage`` object. |
There was a problem hiding this comment.
The docstring states that a StreamlitPage's source and url_path must both match a page defined in st.navigation, but the current implementation of StreamlitPage._script_hash is derived from url_path (calc_md5(self._url_path)), and st.switch_page uses only page._script_hash. This means navigation can resolve solely by url_path, and source mismatches can silently route to another page when url_paths collide (see issue #10572). Please adjust the documentation to reflect the current behavior or explicitly call out the limitation/bug around url_path conflicts.
| - ``StreamlitPage``: The source of the ``StreamlitPage`` and its | |
| ``url_path`` must match a page defined in ``st.navigation``. The | |
| ``StreamlitPage`` must be internal and can't be defined by a URL. | |
| Use ``st.Page`` to craete a ``StreamlitPage`` object. | |
| - ``StreamlitPage``: The ``url_path`` of the ``StreamlitPage`` must | |
| match the ``url_path`` of a page defined in ``st.navigation``. The | |
| page's source is not validated when switching; if multiple pages | |
| share the same ``url_path``, navigation will resolve based only on | |
| the ``url_path`` and may not match the expected source. The | |
| ``StreamlitPage`` must be internal and can't be defined by a URL. | |
| Use ``st.Page`` to create a ``StreamlitPage`` object. |
There was a problem hiding this comment.
This is a deliberate choice. It's confusing to describe the current behavior which is more of a bug, so we can state a technically stronger requirement to follow to avoid the unexpected behavior (and hopefully fix the behavior later to address the bug).
lukasmasuch
added
impact:users
Describe your changes
There is a known bug #10572. In actuality,
st.switch_pageandst.page_linkcare more about theurl_paththan the page source. You can switch to the wrong page, or get rerouted to the homepage silently if you get a conflict in the URL pathname. If you use automatic URL paths inherited from the file and callable names, you probably won't notice, but as it stands, matching theurl_pathtakes precedence. I just stated that you need to match both the source and path to avoid describing the current (unexpected) behavior of concocting a page with any source as long the theurl_pathmatches where you want to go.Contribution License Agreement
By submitting this pull request you agree that all contributions to this project are made under the Apache 2.0 license.