✅ 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.

✅ PR preview is ready!

• Bind widgets to query params - Part 4 #13722
• Bind widgets to query params - Part 3 #13683 👈 (View in Graphite)
• Bind widgets to query params - Part 2 #13682
• Bind widgets to query params - Part 1 #13681
• develop

This stack of pull requests is managed by Graphite. Learn more about stacking.

📈 Frontend coverage change detected

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

• Current PR: 86.3300% (13662 lines, 1867 missed)
• Latest develop: 86.2500% (13540 lines, 1861 missed)

🎉 Great job on improving test coverage!

📊 View detailed coverage comparison

📉 Python coverage change detected

The Python unit test coverage has decreased by 0.0033%

• Current PR: 93.1176% (23175 statements, 1595 missed)
• Latest develop: 93.1209% (23157 statements, 1593 missed)

✅ Coverage change is within normal range.

📊 View detailed coverage comparison

@cusor review

Summary

This PR (Part 3 of a series) adds a bind parameter to st.checkbox, st.toggle, and st.color_picker widgets, enabling two-way synchronization between widget values and URL query parameters. The implementation includes:

• URL seeding: Widgets initialize from URL query params on page load
• URL sync: Widget value changes update the URL in real-time
• Default cleanup: URL param is removed when widget returns to its default value
• Hex color validation: Color picker validates and normalizes hex colors from URLs
• Error handling: New StreamlitInvalidBindValueError for invalid bind values
• Reusable hook: useQueryParamBinding hook extracted for frontend consistency

Code Quality

Python Backend (Good)

The implementation follows Streamlit patterns well:

• bind is properly added as a keyword-only argument in all three widget APIs
• The BindOption type annotation is correctly used
• Documentation is comprehensive in docstrings with clear explanations
• Module-level regex _HEX_COLOR_RE at line 55 of color_picker.py follows best practices for static data
• The _normalize_hex_color helper function is appropriately scoped as a module-private function

# Compiled regex for validating hex colors (#RGB or #RRGGBB format)
_HEX_COLOR_RE = re.compile(r"^#(?:[0-9a-fA-F]{3}){1,2}$")

Frontend TypeScript (Good)

• The useQueryParamBinding hook is well-designed with proper cleanup in the useEffect
• Uses the effect appropriately for external system synchronization (registering with WidgetStateManager)
• Dependencies array is complete and correct
• The hook follows the established pattern for similar bindings in the codebase

  useEffect(() => {
    // Treat null and undefined the same - no binding
    if (!queryParamKey) {
      return
    }

    widgetMgr.registerQueryParamBinding(
      widgetId,
      queryParamKey,
      valueType,
      defaultValue,
      options?.urlFormat,
      options?.optionStrings
    )

    return () => {
      widgetMgr.unregisterQueryParamBinding(widgetId)
    }
  }, [
    widgetMgr,
    widgetId,
    queryParamKey,
    valueType,
    defaultValue,
    options?.urlFormat,
    options?.optionStrings,
  ])

Protobuf Changes (Good)

• Uses optional string query_param_key which is backwards compatible
• Field numbers are sequential and don't conflict with existing fields
• Appropriate comments added for documentation

Test Coverage

Python Unit Tests (Excellent)

Coverage is comprehensive with parameterized tests for checkbox/toggle:

• test_bind_query_params_sets_query_param_key: Verifies proto field is set correctly
• test_bind_query_params_without_key_raises_exception: Tests the required key validation
• test_no_bind_does_not_set_query_param_key: Negative test for non-bound widgets
• test_invalid_bind_value_raises_exception: Tests error handling for invalid bind values

The tests use @parameterized.expand to cover both checkbox and toggle efficiently.

TypeScript Unit Tests (Excellent)

The useQueryParamBinding.test.ts covers:

• Registration with valid queryParamKey
• No registration when queryParamKey is undefined
• Proper unregistration on unmount
• Options passing (urlFormat, optionStrings)
• Re-registration when queryParamKey changes

Component tests (Checkbox.test.tsx, ColorPicker.test.tsx) verify:

• Registration on mount with queryParamKey set
• Unregistration on unmount
• No registration when queryParamKey is not set
• Binding with different default values

E2E Tests (Excellent)

Comprehensive coverage for all three widgets (checkbox, toggle, color_picker):

• test_*_query_param_seeding: Tests URL param → widget initialization
• test_*_query_param_updates_url: Tests widget → URL sync
• test_*_query_param_default_*: Tests default value handling and param removal
• test_*_query_param_invalid_value: Tests graceful handling of invalid URL values

E2E tests follow best practices:

• Use expect() for auto-wait assertions
• Use helper utilities from app_utils (e.g., click_checkbox, get_toggle)
• Include negative assertions (param should NOT be in URL)
• Use wait_for_app_loaded and wait_for_app_run appropriately

Backwards Compatibility

Fully Backwards Compatible

• The bind parameter defaults to None - existing code works unchanged
• Proto changes use optional fields with new field numbers
• No changes to existing widget behavior when bind is not specified
• The validation in register_widget only runs when bind is not None

Security & Risk

Low Risk

• Input validation is proper: Invalid bind values raise clear errors
• Color picker validates hex format from URL params, preventing injection
• Invalid URL values are gracefully handled (widget uses default, param is cleared)
• No new external dependencies introduced

Minor Consideration: The hex color normalization in ColorPickerSerde.deserialize raises a ValueError for invalid hex colors, which the widget manager handles appropriately.

Recommendations

No blocking issues found. The following are minor observations:

1. Good practice already followed: The PR correctly adds "bind" to the excluded parameters list in widgets_test.py with an explanatory comment, ensuring it doesn't affect widget identity computation.

2. Documentation consistency: The bind parameter documentation is consistent across all three widgets, which is good for user experience.

3. Test organization: The E2E tests properly increment the element counts (CHECKBOX_ELEMENTS, TOGGLE_ELEMENTS, NUM_COLOR_PICKERS) to account for the new test widgets added to the app files.

Verdict

APPROVED: This PR is well-implemented with comprehensive test coverage across Python unit tests, TypeScript unit tests, and E2E tests. The code follows established patterns, is fully backwards compatible, and includes proper error handling. The reusable useQueryParamBinding hook provides a clean abstraction for future widget bindings.

This is an automated AI review using opus-4.5-thinking. Please verify the feedback and use your judgment.

📈 Significant bundle size change detected

Please verify that this change is expected.

📊 View detailed bundle comparison