Inconsistent space encoding in query params / Encode spaces as `+` with `bind="query-params"`

[JosephMarinier]

Checklist

• I have searched the existing issues for similar issues.
• I added a very descriptive title to this issue.
• I have provided sufficient information below to help reproduce this issue.

Summary

When a widget has bind="query-params" and the user sets a value with spaces, they are encoded as %20. If the code then sets another value in st.query_params, all spaces become encoded as +.

Reproducible Code Example

import streamlit as st

st.selectbox("Set query param `a`", options=("default", "value with spaces"), key="a", bind="query-params")

if st.button("Set query param `b`"):
    st.query_params["b"] = "value with spaces"

Steps To Reproduce

1. Try the code above
2. Click on the first button
3. Notice ?a=value%20with%20spaces encodes spaces as %20.
4. Click on the second button
5. Notice ?a=value+with+spaces&b=value+with+spaces encodes spaces as +, including the a query param from before.

Expected Behavior

I would expect spaces to always be encoded as +, as it has always been the case for st.query_params["b"] = "value with spaces".

Current Behavior

The spaces in values from widgets that have bind="query-params" are encoded as %20.

Is this a regression?

• Yes, this used to work in a previous version.

Debug info

• Streamlit version: 1.56.0
• Python version: 3.11.9
• Operating System: macOS
• Browser: Chrome

Additional Information

No response

[github-actions]

If this issue affects you, please react with a 👍 (thumbs up emoji) to the initial post.

Your feedback helps us prioritize which bugs to investigate and address first.

[github-actions]

This is a valid bug caused by inconsistent space encoding between two different code paths that update URL query parameters. When a widget with bind="query-params" updates the URL, the frontend uses the query-string npm library (queryString.stringify), which internally calls encodeURIComponent and encodes spaces as %20. However, when the backend updates query params via st.query_params["key"] = "value", it uses Python's urllib.parse.urlencode (which calls quote_plus), encoding spaces as +. The backend path sends the entire query string to the frontend via a page_info_changed ForwardMsg, which overwrites the URL — converting all previously %20-encoded spaces to +. Both encodings are valid per RFC 3986 / HTML form spec, but the inconsistency is confusing and causes URL content to change unexpectedly.

The fix would involve aligning both paths to use the same encoding convention. Since + for spaces has been the longstanding behavior of st.query_params, the frontend's updateUrlParam method in WidgetStateManager.ts (around line 1383) could be adjusted to produce +-encoded spaces, or alternatively query-string's encode option could be customized.

Related Issues

• #9878 — (CommunityCloud) Moving slider seems to generate 2 new (empty) window.history states: Related query-params + widget interaction bug involving window.history state management, though different root cause.
• #9664 — Preserve URL fragment identifier / anchor when updating query params: Related URL handling issue where st.query_params updates inadvertently strip URL fragments, showing a similar pattern of URL manipulation side effects.
• #14670 — Set state of a widget with bind="query-params": Filed by the same author on the same day, covering another aspect of bind="query-params" behavior (programmatic state setting).

---

This is an automated triage comment using claude-4.6-opus-high-thinking. Please verify the suggested labels and related issues.

[sfc-gh-lwilby]

Thanks for the detailed report! We've confirmed this is a valid bug.

The inconsistency comes from two different code paths handling query param encoding: the frontend bind="query-params" path uses encodeURIComponent (spaces → %20), while the backend st.query_params path uses Python's urllib.parse.urlencode (spaces → +). When both interact, the backend overwrites the URL and converts all %20 to +.

We'll align both paths to use consistent encoding.