• [DynamicContainers] Dynamic Tabs #13910 👈 (View in Graphite)
• [DynamicContainers] foundational work adding .open properties #13867 : 2 other dependent PRs (#13868 , #13914 )
• [DynamicContainers] foundational work adding new delta generators  #13851
• 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 adds dynamic tabs functionality to st.tabs() via new key and on_change parameters. When on_change="rerun" is set, Streamlit reruns the app on tab switch, enabling lazy execution of tab content through the .open property on each tab. The implementation spans backend (Python widget registration and state management), frontend (widget state syncing and programmatic tab control), and tests (Python unit tests and E2E playwright tests).

Changed files:

• lib/streamlit/elements/layouts.py — New key/on_change params, _TabsSerde, widget registration
• frontend/lib/src/components/elements/Tabs/Tabs.tsx — Widget state syncing, CSS class support, programmatic control
• frontend/lib/src/components/core/Block/Block.tsx — Pass fragmentId to Tabs
• e2e_playwright/st_tabs.py / st_tabs_test.py — E2E test app and tests
• lib/tests/streamlit/elements/layouts_test.py — Python unit tests

Code Quality

Backend (Python):
The backend implementation is clean and well-structured. The _TabsSerde dataclass follows the existing serialization pattern. Input validation is solid, and the widget registration logic is clear. Good defensive coding with the current_tab_label not in tabs fallback (line 814).

Frontend (TypeScript):
The changes are mostly well-integrated with the existing Tabs component. Two concerns:

1. useEffect for programmatic tab sync (lines 98–112 in Tabs.tsx): The activeTabKey is included in the dependency array but is only read for a guard condition (defaultTabIndex !== activeTabKey). This means the effect body re-executes on every user tab click even though it will be a no-op (because defaultTabIndex hasn't changed). While not a bug, this is wasteful. Consider removing activeTabKey from the dependency array with an ESLint suppression comment, or restructuring the logic to derive the state during render instead of in an effect.

2. Stale docstring (lines 606–611 in layouts.py): The .. note:: block still says "Tabs do not currently support conditional rendering." This is now inaccurate since on_change="rerun" enables exactly that. The docstring should be updated to reflect the new capability.

Test Coverage

Python unit tests (9 new tests): Good coverage of:

• Invalid on_change values
• .open state with on_change="rerun" (with and without default)
• Block ID setting (stateful vs non-stateful)
• Session state integration
• Proto tab index correctness

E2E tests (2 new tests): Good coverage of:

• Lazy execution (only active tab's content runs)
• Programmatic tab control via session state
• Negative assertions (inactive tab content not visible)

Missing frontend unit tests: No new tests were added to Tabs.test.tsx. This is a significant gap for a feature that introduces:

• Widget state management (widgetMgr.setStringValue on tab change)
• Programmatic tab switching via defaultTabIndex changes
• CSS class name from key prop (convertKeyToClassName)
• The isDynamic code path behavior

Frontend unit tests should be added at minimum for:

• Verifying widgetMgr.setStringValue is called when a dynamic tab is clicked
• Verifying widgetMgr.setStringValue is NOT called for non-dynamic tabs
• Verifying the CSS class from key is applied
• Verifying programmatic tab switching when defaultTabIndex changes

Missing Python tests:

• No test for on_change="ignore" explicitly verifying .open is None (though this is implicitly covered by the default behavior tests, an explicit test would be clearer)
• No test verifying that key without on_change does NOT set .open or register a widget

Backwards Compatibility

The changes are mostly backwards compatible:

• Existing st.tabs(["A", "B"]) calls continue to work identically (no state tracking, .open is None)
• New parameters (key, on_change) are keyword-only with safe defaults (None)
• The on_change="ignore" path correctly falls back to non-stateful behavior

Potential issue — key without on_change triggers unintended reruns:
When key is provided without on_change (e.g., st.tabs(["A", "B"], key="my_tabs")):

• Backend sets block_proto.id = element_id (for CSS class generation) but does NOT call register_widget
• Frontend sees non-empty widgetId → sets isDynamic = true
• User clicks a tab → widgetMgr.setStringValue(...) is called with { fromUi: true } → triggers a backend rerun
• Backend reruns but has no registered widget for this ID, so the state update is ignored

This causes unnecessary reruns whenever a user switches tabs with key but no on_change. Users providing key only for CSS styling would experience unexpected performance degradation. The frontend should differentiate between "has a key for CSS" and "is a dynamic widget." One approach: only call setStringValue when a dedicated flag (e.g., a isDynamic or isStateful field in the protobuf) is set, rather than inferring dynamism from the presence of a widget ID.

Security & Risk

• No security concerns identified. The widget state stores only tab labels (strings) that the developer already defines.
• The _TabsSerde.deserialize correctly validates against None and falls back to the default.
• The current_tab_label not in tabs validation prevents stale state from breaking the UI.
• Low regression risk for existing non-dynamic tabs since the new code paths are gated behind is_stateful and isDynamic checks.

Accessibility

• Tab accessibility is handled by the BaseUI Tabs component (tabs-motion), which provides ARIA roles, keyboard navigation, and aria-selected attributes.
• No new accessibility concerns introduced. The dynamic behavior is transparent to assistive technology — tab switching still works via standard ARIA tab patterns.
• The activateOnFocus prop is maintained, preserving keyboard navigation.

Recommendations

1. [Bug] Fix key-without-on_change causing unintended reruns. The frontend should not call widgetMgr.setStringValue when the tabs are not actually registered as a widget. Consider adding a boolean field to the proto (e.g., is_dynamic on TabContainer) or checking for widget registration on the frontend, rather than inferring dynamism from Boolean(widgetId).

2. [Testing] Add frontend unit tests in Tabs.test.tsx. At minimum, test:

   • widgetMgr.setStringValue is called on tab click for dynamic tabs
   • widgetMgr.setStringValue is NOT called for non-dynamic tabs
   • CSS class from key is applied to the container
   • Programmatic tab switching when defaultTabIndex prop changes

3. [Docs] Update the stale docstring note at layouts.py lines 606–611. The note currently states tabs don't support conditional rendering, but on_change="rerun" now enables it. Update it to mention the new capability, e.g.:

   "By default, all tab content is computed and sent to the frontend. Use on_change="rerun" to enable lazy execution, where only the active tab's content runs."

4. [Minor] Consider removing activeTabKey from the useEffect dependency array (lines 98–112 in Tabs.tsx) to avoid unnecessary effect re-executions on every user tab click. The guard defaultTabIndex !== prevDefaultTabIndexRef.current already prevents incorrect behavior.

5. [Minor] Consider adding a test for on_change="ignore" with key to explicitly verify that .open remains None and no widget state is registered, documenting the expected behavior of this combination.

Verdict

CHANGES REQUESTED: The key parameter without on_change causes unintended reruns due to the frontend treating any non-empty widgetId as a dynamic widget. This is a user-facing bug that should be fixed before merge. Additionally, frontend unit tests are missing for significant new behavior.

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

📈 Frontend coverage change detected

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

• Current PR: 87.1200% (14122 lines, 1818 missed)
• Latest develop: 87.1000% (14110 lines, 1820 missed)

✅ Coverage change is within normal range.

📊 View detailed coverage comparison

Summary

This PR adds key and on_change parameters to st.tabs(), enabling stateful, lazily-executed tabs. When on_change="rerun", switching tabs triggers a full rerun and each tab's .open property reflects whether it is the active tab, allowing users to skip expensive computation in hidden tabs. Programmatic tab switching via st.session_state is also supported. When only key is provided (no on_change), a CSS class is applied for styling without registering widget state.

Key changes:

• Protobuf: Adds optional string widget_id field to TabContainer in Block.proto.
• Backend: Adds key/on_change parameters to st.tabs(), widget registration via register_widget, a _TabsSerde dataclass, and .open state management.
• Frontend: Passes fragmentId to the Tabs component, sends tab label to backend via widgetMgr.setStringValue on tab switch for dynamic tabs, syncs active tab on programmatic defaultTabIndex changes, and applies st-key- CSS class.
• Tests: 10 new Python unit tests, 3 new E2E tests, and 6 new frontend unit tests.

Code Quality

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

Backend (lib/streamlit/elements/layouts.py):

• The _TabsSerde dataclass is simple and correct. The @dataclass decorator is used appropriately.
• The is_stateful flag cleanly separates stateful from non-stateful code paths.
• Label validation at line 814 handles the edge case where widget state refers to a removed tab label.
• The check_widget_policies call correctly passes on_change=None since the tab's on_change is a string, not a callback — callbacks are not yet supported, and this is a reasonable MVP design.
• The three-way code path (stateful / key-only / neither) at lines 779-822 is clear and well-documented.

Frontend (Tabs.tsx):

• The allTabLabels memoization (line 74-81) prevents unnecessary effect re-runs, following best practices.
• The useEffect at line 100-114 for syncing programmatic tab changes is appropriate: it synchronizes with an external system (backend state changes), which is a valid use case per the AGENTS.md effect guidelines. The prevDefaultTabIndexRef pattern correctly detects actual changes.
• The onChange handler (line 164-177) cleanly separates local UI state updates from widget state updates, guarding the latter behind isDynamic.
• The CSS key class is derived from block.id (line 150), which works for both key-only and widget modes.

Minor observations:

1. In e2e_playwright/st_tabs.py line 149, the comment for the key-only section is missing a blank line separator from the previous code block:

        st.write("Gamma tab content")
# Key-only (no on_change) — should NOT trigger reruns on tab switch

This is a minor formatting issue that doesn't affect functionality.

2. The typing test file (lib/tests/streamlit/typing/tab_container_types.py) could benefit from a type assertion for the new parameters (e.g., tabs(["A", "B"], key="k", on_change="rerun")), but the existing assertions already cover the return type and .open property correctly.

Test Coverage

Test coverage is thorough and well-designed:

Python unit tests (10 new tests in layouts_test.py):

• Invalid on_change value validation
• .open state with and without default
• Proto field presence for id and widget_id across all three modes
• Session state accessibility with key
• Correct default_tab_index in proto
• on_change="ignore" producing no state tracking (good anti-regression check)

Frontend unit tests (6 new tests in Tabs.test.tsx):

• widgetMgr.setStringValue called on tab click for dynamic tabs
• widgetMgr.setStringValue NOT called for non-dynamic tabs (anti-regression)
• Programmatic tab sync via rerender with updated defaultTabIndex
• CSS class applied with key (both with and without widget)
• CSS class NOT applied without key (anti-regression)

E2E tests (3 new tests in st_tabs_test.py):

• Lazy execution: verifies execution counts across tab switches
• Programmatic control: verifies session state button control
• Key-only mode: verifies no rerun on tab switch (good anti-regression)

The E2E tests correctly use wait_for_app_run(app) after clicks that should trigger reruns, and correctly omit it for key-only tabs where no rerun should happen. The tests use expect for auto-wait assertions and follow the locator priority guidelines (role-based and text-based).

One note: the E2E tests don't include fragment-scoped testing (@st.fragment), which is listed as a recommended scenario in the E2E AGENTS.md. Since fragmentId is now being passed to the component, a fragment-scoped test would increase confidence. This could be a follow-up item.

Backwards Compatibility

This PR is fully backwards compatible:

• Protobuf: The new optional string widget_id field (field 2) in TabContainer is additive. Existing messages without this field will have it absent, which the frontend correctly treats as non-dynamic behavior.
• Python API: Both key and on_change parameters are optional keyword-only arguments with None defaults, preserving existing call signatures.
• Default behavior: Without on_change, tabs behave identically to before — all tab content runs, .open returns None, and no widget state is registered.
• Frontend: The isDynamic check (line 71) gates all new behavior. Without widgetId in the proto, the component behaves exactly as before.

Security & Risk

No security concerns identified:

• The widget state contains only user-visible tab labels (strings), not sensitive data.
• The on_change parameter is validated against a strict allowlist ({"ignore", "rerun"}) at line 766.
• The check_widget_policies call ensures proper widget registration in the correct scope.
• Label validation prevents stale widget state from referencing non-existent tabs.

Risk assessment: Low risk. The new functionality is cleanly gated behind the on_change="rerun" parameter. The non-dynamic path is unchanged.

Accessibility

No accessibility concerns. The PR does not modify any ARIA attributes, roles, or keyboard behavior. The tabs continue to use BaseUI's Tabs component with proper tab and tabpanel roles. The activateOnFocus prop remains enabled for keyboard navigation.

Recommendations

1. Minor formatting: Add a blank line before the key-only section comment in e2e_playwright/st_tabs.py (line 149) for consistency:

   # Before:
           st.write("Gamma tab content")
   # Key-only (no on_change) — ...
   
   # After:
           st.write("Gamma tab content")
   
   # Key-only (no on_change) — ...

2. Typing tests: Consider adding type assertions for the new parameters in lib/tests/streamlit/typing/tab_container_types.py:

   # With new parameters
   assert_type(tabs(["A", "B"], key="k", on_change="rerun"), Sequence[TabContainer])
   assert_type(tabs(["A", "B"], on_change="ignore"), Sequence[TabContainer])

3. Follow-up consideration: A fragment-scoped E2E test (@st.fragment) would be valuable for validating the fragmentId integration. This could be done in a follow-up PR.

These are all minor suggestions and none are blocking.

Verdict

APPROVED: Well-designed, backwards-compatible feature addition with comprehensive test coverage, clean code paths, and proper separation between stateful and non-stateful tab behavior.

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

Consolidated Code Review: PR #13910 — [DynamicContainers] Dynamic Tabs

Summary

This PR adds key and on_change parameters to st.tabs(), enabling stateful, lazily-executed tabs. When on_change="rerun", switching tabs triggers a script rerun, and each tab's .open property indicates the active tab (True/False), allowing apps to skip expensive work in hidden tabs. Programmatic tab switching is supported via st.session_state.

Changes span the full stack:

• Protobuf: Added optional string widget_id to TabContainer message.
• Backend: New key/on_change parameters on st.tabs(), widget registration via register_widget, _TabsSerde dataclass, .open state management, and fallback logic for stale labels.
• Frontend: Tabs.tsx reads the new widgetId, calls widgetMgr.setStringValue on tab switch for dynamic tabs, and syncs programmatic defaultTabIndex changes via a useEffect. Block.tsx passes fragmentId to the Tabs component.
• Tests: 8 new Python unit tests, 3 new frontend unit tests, and 3 new E2E tests.

Reviewer Agreement

Both reviewers (gpt-5.3-codex-high and opus-4.6-thinking) agreed on:

• Clean implementation following existing Streamlit patterns well
• Good test coverage for core flows (lazy execution, programmatic control, key-only tabs, .open behavior, session state, proto fields)
• Full backwards compatibility — default behavior is preserved, new params are optional with None defaults, protobuf field is optional
• No security concerns — widget state only stores developer-provided tab labels
• No accessibility regressions — continues using BaseWeb's UITabs with proper ARIA semantics
• Duplicate tab labels are a known edge case with label-based identification in dynamic mode

Reviewer Disagreement

The key disagreement is on severity:

Resolution: Duplicate Tab Labels

After verifying the code, tabs.index(current_tab_label) always resolves to the first occurrence — meaning selecting a later duplicate snaps back to the first on rerun. However, this is consistent with existing behavior: the default parameter already works via tabs.index(default), which has the same first-occurrence semantics. Duplicate tab labels have always been inherently ambiguous. This is a pre-existing limitation, not a regression introduced by this PR. A docstring note would be helpful but this is non-blocking.

Resolution: Stale Session State Fallback

After inspecting the code, there is a real (minor) inconsistency: when register_widget returns a stale label (e.g., "OldTab" from a previous run with different tabs), the local current_tab_label is corrected to the fallback, but st.session_state[key] retains the stale value until the next user interaction. However:

1. This only occurs in the narrow edge case where tab labels change between reruns while stale state exists.
2. The rendered tab will be correct (the fallback applies to the proto's default_tab_index).
3. The inconsistency is transient — it resolves on the next tab switch.

This is a valid observation worth addressing in a follow-up, but it is not a blocking issue for initial merge.

Code Quality

The implementation is clean and well-structured:

• Backend: _TabsSerde dataclass follows the established serde pattern. The is_stateful flag cleanly separates dynamic and non-dynamic paths. Good use of check_widget_policies and compute_and_register_element_id.
• Frontend: The isDynamic flag based on widgetId presence is clean. The useMemo for allTabLabels is a good optimization over the previous mutable array approach. The useEffect for programmatic sync with prevDefaultTabIndexRef is acceptable.
• Protobuf: optional string widget_id on TabContainer is well-designed, allowing the frontend to distinguish between "no widget" and "widget present."
• Tests: All Python tests have docstrings. E2E tests use wait_for_app_run, stable locators, and include negative assertions.

Test Coverage

Strong coverage for core functionality. Both reviewers noted the following gaps:

• No test for duplicate tab labels with on_change="rerun" (both reviewers)
• No test asserting st.session_state[key] value after stale label fallback (gpt-5.3-codex-high)
• No test for dynamic tabs inside @st.fragment (opus-4.6-thinking)
• No typing tests in lib/tests/streamlit/typing/ for the new key and on_change parameters (opus-4.6-thinking)

Recommendations

1. Document key behavior without on_change="rerun": When on_change is not "rerun", the key parameter currently has no effect (no widget registration, no session state). This should be noted in the docstring to avoid user confusion.

2. Add a note about duplicate tab labels: A one-line docstring note that duplicate labels with on_change="rerun" always resolve to the first occurrence would help prevent surprise.

3. Consider fixing the stale session state fallback (follow-up): When a stale label falls back to the default, also update the widget state so st.session_state[key] is consistent with the rendered tab in the same run.

4. Add typing tests (follow-up): Consider adding a typing test file at lib/tests/streamlit/typing/tabs_types.py for the new key and on_change parameters.

5. Test inside @st.fragment (follow-up): The fragmentId propagation via Block.tsx should be verified end-to-end with dynamic tabs inside a fragment.

Verdict

APPROVED — This is a well-implemented feature addition with clean code, solid test coverage, full backwards compatibility, and no security or accessibility concerns. The edge cases identified by reviewers (duplicate labels, stale session state fallback) are real but non-blocking: the duplicate label behavior is consistent with pre-existing semantics, and the stale state issue is a narrow transient inconsistency. The recommendations above are suggested as follow-up improvements.

Consolidated review by opus-4.6-thinking. Individual reviews below.

@lukasmasuch also updated the other two widget PRs with the same changes.