✅ PR preview is ready!

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

📈 Frontend coverage change detected

The frontend unit test (vitest) coverage has increased by 0.0500%

• Current PR: 86.8200% (13878 lines, 1829 missed)
• Latest develop: 86.7700% (13876 lines, 1835 missed)

✅ Coverage change is within normal range.

📊 View detailed coverage comparison

Summary

This PR adds bind="query-params" support to st.checkbox and st.toggle, enabling two-way sync between widget values and URL query parameters. The implementation follows the same pattern established by the st.color_picker bind feature. It also includes a backend improvement to the _seed_widget_from_url logic in session_state.py that simplifies default-value clearing, plus a minor consistency cleanup for ColorPicker.tsx.

Key changes:

• Proto: New optional string query_param_key = 11 field in Checkbox.proto.
• Backend: bind parameter added to checkbox() and toggle() APIs, with session_state seeding logic simplified.
• Frontend: Checkbox.tsx integrates queryParamBinding via useBasicWidgetState, with getDefaultStateFromProto/getCurrStateFromProto now falling back to false instead of potentially null.
• Tests: Comprehensive E2E, Python unit, frontend unit, and typing tests added.

Code Quality

The code is clean, well-structured, and follows established patterns in the codebase:

• The checkbox.py backend implementation mirrors the existing color_picker.py bind pattern exactly — bind as a keyword-only parameter, query_param_key proto field, and clearable=False for the boolean widget type.
• The Checkbox.tsx frontend follows the same queryParamBinding const pattern that ColorPicker.tsx now uses (after the cleanup in this PR).
• The getDefaultStateFromProto and getCurrStateFromProto functions now properly fall back to false instead of potentially returning undefined/null (Checkbox.tsx:248-253). This is correct for a boolean widget and matches the type contract.
• The session_state simplification (session_state.py:1036) removes unnecessary conditions (parsed_value != serialized_default and not is_empty_url_value(url_value)) and replaces them with a straightforward deserialized_value == default_value check. This is logically correct: if the URL value resolves to the widget's default, it should always be cleared from the URL, regardless of how it was encoded.
• The ColorPicker.tsx cleanup (extracting queryParamBinding to a const) improves readability and consistency.

Minor observations:

• The queryParamBinding object in Checkbox.tsx (lines 54-61) is created inline on every render. However, useBasicWidgetState correctly destructures it into primitives and memoized values internally, so this does not cause unnecessary effect re-runs. This is consistent with the ColorPicker.tsx pattern.

• In the E2E tests, the regex patterns like re.compile(r"bound_toggle") could theoretically match bound_toggle_true in the URL. In practice this is safe because widgets at their default value never appear in the URL, but slightly more specific patterns like r"bound_toggle=" or r"[?&]bound_toggle=" would be more defensive. This is a very minor style nit and does not affect test correctness.

Test Coverage

Test coverage is thorough and well-structured:

E2E tests (checkbox + toggle):

• URL seeding from query params (both default False and overriding True default)
• URL updates on user interaction (click to change, click back to default)
• Default value cleanup from URL
• Invalid URL value handling
• Each test uses expect for auto-wait assertions (no assert)
• Negative checks included (e.g., not_to_have_url to verify param removal)

Python unit tests:

• bind='query-params' sets proto query_param_key field
• Missing key raises StreamlitAPIException
• Invalid bind value raises StreamlitInvalidBindValueError
• No bind leaves query_param_key empty
• Parameterized across both st.checkbox and st.toggle
• Session state tests updated for the new default-clearing behavior, with a new test for the deserialized_value == default_value case

Frontend unit tests:

• Query param binding registration/unregistration lifecycle
• No registration when queryParamKey is not set
• Toggle variant with default: true

Typing tests:

• assert_type checks for both checkbox and toggle with bind="query-params"

The element count constants (CHECKBOX_ELEMENTS = 19, TOGGLE_ELEMENTS = 19) have been correctly updated to reflect the 2 new widgets added to each e2e script.

Backwards Compatibility

This PR is fully backwards compatible:

• The bind parameter defaults to None, preserving existing behavior for all current users.
• The proto field query_param_key is optional with field number 11 (new), so older frontends will simply ignore it.
• The session_state _seed_widget_from_url change is a behavioral refinement: it now clears URL params that match the default value in all cases (previously it only cleared some cases). This is an improvement — users with ?widget=default_value in their URL will see the redundant param cleaned up. This cannot break existing functionality since the widget value remains at the default either way.

Security & Risk

No security concerns identified:

• The URL query parameter binding only reads/writes URL params that the developer explicitly opts into via bind="query-params" with a user-provided key.
• Invalid URL values are properly sanitized: they fall back to the widget default and the invalid param is cleared from the URL.
• The clearable=False setting for checkbox/toggle correctly prevents empty URL values from being accepted.

Accessibility

No accessibility concerns. The checkbox and toggle widgets themselves are unchanged visually and functionally — only the URL binding behavior is new. The existing aria-label={element.label} and keyboard interaction patterns remain intact.

Recommendations

No blocking issues found. A few minor suggestions:

1. E2E regex specificity (very minor): Consider using more specific regex patterns in toggle E2E tests to avoid potential ambiguity between bound_toggle and bound_toggle_true. For example, re.compile(r"bound_toggle=") instead of re.compile(r"bound_toggle"). This is non-blocking since the tests are correct in practice.

2. Color picker test cleanup (nice-to-have): The st_color_picker_test.py changes (replacing r"^((?!bound_color=).)*$" with not_to_have_url(re.compile(r"bound_color"))) are a nice readability improvement. Consider applying this pattern retroactively to any similar tests elsewhere if they exist.

Verdict

APPROVED: Clean, well-tested implementation that follows established patterns for binding widgets to URL query params. The session_state simplification is a correct behavioral improvement, and the PR is fully backwards compatible.

This is an automated AI review by opus-4.6-thinking.