---
title: Tab selection
summary: Manages tab-bar selection state and raises tab-change events, across two independent implementations (SAIFTabBar and SAIFTabs).
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-08-17
library: SAIF.Presentation.Web.Controls.V2
reference_type: package
operation_id: OP-V2-TABS-001
trigger: Tab LinkButton click (postback)
---

# Tab selection

This operation covers tab-selection behavior across the library's two structurally independent tab-bar implementations: the declarative `SAIFTabBar` (markup-persisted tab collection) and the imperative `SAIFTabs` (code-driven `AddTab`/`InsertTab`/`RemoveTab`)*.

| Field | Value |
| --- | --- |
| **Operation ID** | OP-V2-TABS-001 |
| **Trigger** | Tab `LinkButton` click (postback). |
| **Inputs** | `SAIFTabBarTabCollection` (declarative) or `ArrayList` of `TabSettings` (imperative). |
| **Outputs** | Updated tab selection state; `TabClicked` event (`SAIFTabBar`) or `BeforeSelectedIndexChanged`/`SelectedIndexChanged` events (`SAIFTabs`). |
| **Primary components** | `SAIFTabBar.RaiseTabClickedEvent`, `SAIFTabBar.CreateChildControls`, `SAIFTabBar.RenderControl`; `SAIFTabs.LinkButtonClick`. |
| **Entry point** | `SAIF.Presentation.Web.Controls.V2\SAIFTabBar.vb`, `SAIF.Presentation.Web.Controls.V2\SAIFTabs.vb` |

## Steps

### SAIFTabBar (declarative)

1. `CreateChildControls` sorts `_Tabs` (by `Order`, then `Text`, via the generic `Sorter(Of SAIFTabBarTab)`), builds one `<li><LinkButton></li>` per tab, and wires `AddHandler lb.Click, AddressOf RaiseTabClickedEvent`.
2. On click, `RaiseTabClickedEvent`:
   - Deselects all tabs when `Mode = TabBarMode.TabBar` (mutually exclusive selection) ([BR-V2-006](../business-rules.md#br-v2-006-saiftabbar-tab-selection-is-mutually-exclusive-in-tabbar-mode)).
   - Selects the clicked tab.
   - Raises the public `TabClicked` event.
3. `RenderControl` applies CSS classes (`Selected`, `SelectedSibling`, `Disabled`, `DisabledSelected`) depending on tab state and `Mode` (`TabBar` vs. `WizardTabBar`).

### SAIFTabs (imperative)

1. Consuming pages call `AddTab`/`InsertTab`/`RemoveTab` to build the tab list (`ArrayList` of `TabSettings`).
2. `LinkButtonClick` (wired per rendered link) matches the clicked link's `ClientID` against tab entries.
3. Raises `BeforeSelectedIndexChanged` (cancelable via `SAIFTabEventArgs.Cancel`) — allowing the host page to intercept/cancel the tab switch.
   - If not canceled: raises `SelectedIndexChanged`, allowing the host page to coordinate visibility of the tab-associated content panel (`DivID`).

- **Delegation**: None into referenced libraries in either implementation; purely local control-tree logic.

## Process flow

The following diagram visualizes the `SAIFTabBar` selection flow only; see the "SAIFTabs (imperative)" steps above for the separate, structurally different flow used by `SAIFTabs` (`ClientID` matching and a cancelable `BeforeSelectedIndexChanged`/`SelectedIndexChanged` pair, with no `Mode`-based deselection or CSS-state rendering step).

```mermaid
flowchart TD
	Start([Tab LinkButton click]) --> Mode{Mode = TabBar?}
	Mode -->|Yes| Deselect[Deselect all other tabs]
	Mode -->|No, WizardTabBar| Skip[Skip deselection]
	Deselect --> Select[Select clicked tab]
	Skip --> Select
	Select --> Raise[Raise TabClicked event]
	Raise --> Render[RenderControl applies CSS classes per tab state]
```

## Failure and edge-case behavior

- `SAIFTabBar` `RenderControl` wraps its rendering logic in a `Try`/`Catch` that writes the exception message, source, and stack trace directly to the output stream on failure — an unusual error-surfacing pattern for a production control*.
- Whether both `SAIFTabBar` and `SAIFTabs` remain actively consumed by downstream applications, or one is deprecated, could not be determined from this library alone**.

> **Note:** Statements marked with * were inferred from code structure, naming conventions, or
> contextual evidence where direct confirmation was not available in source artifacts. Statements
> marked with ** could not be confirmed; treat as unknown until verified.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

## Sources
- SAIF.Presentation.Web.Controls.V2\SAIFTabBar.vb
- SAIF.Presentation.Web.Controls.V2\SAIFTabs.vb
- SAIF.Presentation.Web.Controls.V2\TabSettings.vb