• [DynamicContainers] Callback support for expanders #14008
• [DynamicContainers] Dynamic Expanders #13888 👈 (View in Graphite)
• [refactor] improve Expander animation with ResizeObserver, smooth interruption, and nullable expanded handling #13934
• [refactor] extract Expander animation logic into useDetailsAnimation hook #13933
• develop

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

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

Summary

This PR implements "dynamic expanders" for Streamlit, adding on_change and key parameters to st.expander(). When on_change="rerun" is set, the expander registers as a widget, tracks its open/closed state in session_state, and triggers a full app rerun on toggle. This enables a "lazy execution" pattern where content inside an expander only runs when it's open. The changes span:

• Backend (lib/streamlit/elements/layouts.py): New key and on_change parameters, widget registration via register_widget, _ExpanderSerde dataclass, and setting .open on the returned ExpanderContainer.
• Frontend (Expander.tsx, Block.tsx): The Expander component now accepts optional widgetMgr, blockId, and fragmentId props. When in widget mode, it calls setBoolValue on toggle to notify the backend. It also shows a loading skeleton while waiting for lazy content.
• E2E tests: Comprehensive tests for lazy execution, programmatic control, nested dynamic expanders, and state preloading.
• Python unit tests: Covers on_change validation, .open attribute, session state access, block ID generation, and widget state.

Code Quality

The code is well-structured and follows existing patterns in the codebase.

Backend:

• The _ExpanderSerde dataclass (lines 65-75 in layouts.py) follows the established serde pattern used by other widgets.
• The widget registration flow mirrors other stateful elements (checkbox, etc.) with proper use of check_widget_policies, compute_and_register_element_id, and register_widget.
• The elif key: branch at line 960 correctly handles the case where a key is provided without on_change="rerun", generating an element ID for CSS class purposes only (consistent with existing behavior for other elements).
• The docstring for the new parameters is thorough and follows the numpydoc style used elsewhere.

Frontend:

• The Expander component cleanly separates widget mode from non-widget mode using const isWidget = Boolean(widgetMgr && blockId).
• The loading skeleton pattern (showing a skeleton while waiting for lazy content) is a good UX choice. The two useEffect hooks for clearing loading state (lines 114-134) are justified by their comments—they sync with external systems (backend content arrival and script run completion).
• The Block.tsx changes properly pass widgetMgr, blockId, and fragmentId to the Expander component.

Minor observations:

1. In layouts.py line 913, the validation if on_change not in {"ignore", "rerun"} is correct, though the type system already constrains this to Literal["ignore", "rerun"]. The runtime check is still valuable since Python doesn't enforce Literal at runtime.

2. The _ExpanderSerde class is prefixed with underscore, consistent with the project convention for module-private symbols.

Test Coverage

Python unit tests (10 new tests): Comprehensive coverage including:

• Invalid on_change validation
• .open attribute for both expanded=True and expanded=False
• Block ID generation with and without on_change
• Session state accessibility
• Widget state propagation to proto

Frontend unit tests (7 new tests): Good coverage of widget mode behavior:

• setBoolValue called on toggle
• No setBoolValue when widgetMgr is absent
• Loading skeleton on empty widget expander
• No skeleton for non-widget expander
• Skeleton clearing on content arrival and script run completion
• CSS class from blockId

E2E tests (5 new tests): Thorough end-to-end coverage:

• Lazy execution counting
• Programmatic control via session state
• Nested dynamic expanders (both click-based and programmatic)
• State preloading (setting inner state before outer is rendered)

The E2E tests include good negative assertions (e.g., verifying execution counts don't change when expanders are closed). The NUMBER_OF_EXPANDERS constant was correctly updated from 15 to 18.

One gap noted: There is no test for using on_change="rerun" inside a @st.fragment, which is mentioned as a common context to verify in the E2E testing guidelines. However, this may be covered in a future PR or may not be relevant at this stage.

Backwards Compatibility

This PR is fully backwards compatible:

• The new key and on_change parameters are keyword-only with safe defaults (None and "ignore" respectively).
• The default behavior (on_change="ignore") preserves the existing non-widget behavior where .open returns None.
• Existing expanders without key or on_change are completely unaffected—no element ID is set, no widget registration occurs.
• The frontend gracefully handles both widget and non-widget modes—when widgetMgr and blockId are absent, the component behaves identically to before.
• The expanded parameter continues to work as before for initial state.

Security & Risk

• No security concerns identified. The widget registration follows the established pattern with proper policy checks (check_widget_policies).
• Low regression risk. The changes are additive and gated behind on_change="rerun". The default code path is unchanged.
• Potential edge case: When on_change="rerun" is used without a key, the auto-generated element ID includes parameters like label, expanded, icon, width, and on_change. If a user changes the label dynamically, the widget ID would change, potentially losing state. This is consistent with how other auto-keyed widgets behave, so it's not a bug, but worth noting.

Accessibility

• The Expander component continues to use semantic <details>/<summary> HTML elements, which are inherently accessible.
• The inert attribute is still properly set on collapsed content to exclude it from screen reader traversal and find-in-page searches.
• The loading skeleton has a data-testid for test targeting but would benefit from an aria-label or role="status" for screen readers to announce loading state. However, this is a pre-existing pattern in the codebase, not introduced by this PR.
• No new interactive elements are added without accessible names.

Recommendations

1. Consider testing in @st.fragment context: The E2E testing guidelines recommend verifying widget behavior within a @st.fragment. Consider adding a test or documenting that this will be covered separately.

2. Minor: docstring note about lazy execution is now outdated. The docstring at line 786-789 still says "All content within the expander is computed and sent to the frontend, even if the expander is closed." This is no longer true when on_change="rerun" is used with conditional execution. Consider updating this note to mention the new behavior, or adding a note that this applies only when on_change="ignore".

3. Consider adding a typing test: The lib/streamlit/AGENTS.md mentions typing tests in lib/tests/streamlit/typing/ for public API. Since key and on_change are new public API parameters, a typing test (e.g., expander_types.py) would catch future typing regressions.

Verdict

APPROVED: Well-implemented feature with thorough test coverage, full backwards compatibility, and clean code that follows established patterns. The recommendations above are minor improvements that could be addressed in follow-up PRs.

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

Summary

Adds stateful st.expander behavior via on_change="rerun" and key support in the backend, plus a new frontend animation hook/utility and loading skeleton handling for dynamic expanders. Updates the protobuf to carry a widget id for expanders and extends unit/e2e coverage for the new behavior.

Code Quality

No blocking issues found. The backend/widget registration flow in lib/streamlit/elements/layouts.py and the frontend animation logic in frontend/lib/src/components/elements/Expander/useDetailsAnimation.ts are well-factored and consistent with existing patterns.

Test Coverage

Good coverage: Python unit tests in lib/tests/streamlit/elements/layouts_test.py, frontend unit tests for the hook/utility and widget mode behavior (useDetailsAnimation.test.ts, animateHeight.test.ts, Expander.test.tsx), and e2e scenarios in e2e_playwright/st_expander_test.py that validate dynamic behavior and ignore-mode non-rerun.

Backwards Compatibility

Default behavior remains on_change="ignore", so existing expanders should behave as before. Stateful behavior is opt-in via on_change="rerun" and does not affect legacy usage.

Security & Risk

No security concerns identified. The main risk is visual/behavioral regression around expander animations and empty content loading, which is mitigated by unit and e2e coverage.

Accessibility

No new accessibility regressions noted. The component continues to use semantic <details>/<summary> with focus-visible styling, and inert is applied only to collapsed content.

Recommendations

1. If the new min-height/skeleton behavior changes the empty-expander visuals, ensure related snapshots are updated in the e2e suite.

Verdict

APPROVED: Changes look safe, backwards compatible, and well-tested.

This is an automated AI review by gpt-5.2-codex-high. Please verify the feedback and use your judgment.

LGTM 👍 with one comment about ID computation. But maybe better to add as a follow up.

Yeah, maybe I can make this change along with handling the CSS class + key, but prior to release cutoff so it won't introduce a change for users.

Summary

This PR adds key and on_change parameters to st.expander, enabling stateful "dynamic" expanders. When on_change="rerun" is set, the expander registers as a widget: toggling triggers a rerun, expanded state is accessible via st.session_state[key] and the .open attribute, and programmatic control is supported. The default on_change="ignore" preserves existing non-widget behavior. The implementation follows the established pattern from st.popover and st.tabs, which already support the same on_change mechanism.

Key changes:

• Proto: Added optional string id field to Block.Expandable to signal widget mode.
• Backend: Widget registration (_ExpanderSerde, register_widget, check_widget_policies) when on_change="rerun".
• Frontend: Expander.tsx gains widgetMgr, blockId, fragmentId props; useDetailsAnimation hook gains onToggle callback.
• Block.tsx: Threads widgetMgr, blockId, and fragmentId to the Expander component.
• Tests: Comprehensive Python unit tests, frontend unit tests, and E2E tests.

Code Quality

The implementation is well-structured and follows established codebase patterns closely.

Backend:

• The widget registration logic mirrors the popover and tabs implementations, ensuring consistency.
• Proper use of check_widget_policies, compute_and_register_element_id, and register_widget.
• Good validation with StreamlitValueError for invalid on_change values.
• The _ExpanderSerde dataclass (pre-existing) is reused cleanly.

Frontend:

• The isWidget determination from element.id is clean and avoids false positives when only blockId is set for CSS key styling.
• handleWidgetToggle uses useCallback with correct dependency arrays.
• useDetailsAnimation hook changes are minimal and well-targeted — only adding the onToggle callback plumbing.
• The animateHeight utility and its test are well-factored with clear cancel/finish lifecycle semantics.

Minor issues:

1. lib/streamlit/elements/layouts.py line 1066–1067: Missing blank line between the end of the if is_stateful: block and expandable_proto = BlockProto.Expandable(). A blank line here would improve readability and separate the two logical sections:

            current_expanded = expander_state.value
        expandable_proto = BlockProto.Expandable()
        expandable_proto.expanded = current_expanded

2. The docstring .. note:: at lines 896–898 says "All content within the expander is computed and sent to the frontend, even if the expander is closed." This is now misleading when on_change="rerun" is combined with the if exp.open: pattern (the primary use case for the new feature), where content is explicitly not computed when closed. Consider updating or qualifying this note.

Test Coverage

Test coverage is thorough and well-organized:

Python unit tests (layouts_test.py): 12 new tests covering:

• Invalid on_change validation
• .open returns correct bool/None values for both modes
• Block ID and expandable ID assignment for rerun vs ignore
• Session state accessibility with explicit key
• Widget state driving the proto expanded value
• Good negative tests: key without on_change does not set block ID; ignore mode does not set IDs.

Frontend unit tests:

• Expander.test.tsx: Widget mode setBoolValue calls, non-widget mode guard, CSS class from blockId, negative assertions.
• useDetailsAnimation.test.ts: Comprehensive coverage of initial state, toggle, rapid double-toggle, backend sync (including null/undefined ClearField), label change reset, ResizeObserver lifecycle, debounce, threshold, zero-content fallback path, cleanup.
• animateHeight.test.ts: Animation creation, custom options, finish/cancel lifecycle and style cleanup semantics.

E2E tests (st_expander_test.py): 6 new tests covering lazy execution, programmatic control, nested expanders (click + button), state preloading across mount/unmount cycles, and ignore-mode no-rerun verification.

Gaps (non-blocking):

• No typing test additions in lib/tests/streamlit/typing/expander_container_types.py for the new on_change and key parameters. Consider adding assert_type checks for expander("Test", on_change="rerun", key="k") to catch typing regressions.
• No @st.fragment E2E test for the dynamic expander (the fragmentId prop is threaded through, but not tested end-to-end). This could be a follow-up.
• Per the E2E AGENTS.md guidance on preferring aggregated scenario tests: the nested tests (test_dynamic_expander_nested and test_dynamic_expander_nested_programmatic_control) cover overlapping setup and could be consolidated. However, the distinct interaction patterns (UI click vs button) justify separate test functions for clarity.

Backwards Compatibility

No breaking changes. Backwards compatibility is well-maintained:

• on_change defaults to "ignore", preserving the current non-widget behavior for all existing code.
• key without on_change="rerun" has no effect (tested explicitly).
• .open property continues to return None by default (tested).
• The proto field id is optional — existing messages without it are unaffected.
• The ExpanderContainer class is unchanged in its public interface; the .open property was already bool | None.

Security & Risk

No security concerns identified. The widget registration follows the same established patterns used by popover and tabs. The check_widget_policies call ensures proper policy enforcement (e.g., preventing use inside @st.cache_data).

Low regression risk: the default behavior is unchanged, and the new code paths are fully gated behind on_change="rerun".

Accessibility

Accessibility is properly maintained:

• The <summary> element is semantically correct for the toggle interaction and has proper :focus-visible styling via StyledSummary.
• The inert attribute on StyledDetailsPanel correctly excludes collapsed content from assistive technology and browser find-in-page, and is properly toggled on expand/collapse.
• No new aria-hidden usage on interactive wrappers.
• Keyboard navigation is preserved through native <summary> behavior.

Recommendations

1. Add a blank line after line 1066 in lib/streamlit/elements/layouts.py to separate the if is_stateful: block from the proto construction.
2. Update or qualify the .. note:: in the expander docstring (lines 896–898) to mention that with on_change="rerun", content can be conditionally computed using if exp.open:.
3. Consider adding typing tests in expander_container_types.py for the new on_change and key parameters.
4. Consider adding a @st.fragment E2E test for the dynamic expander in a follow-up PR.

Verdict

APPROVED: Well-implemented feature following established widget patterns with comprehensive test coverage and full backwards compatibility. The minor suggestions above are non-blocking improvements.

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