---
title: SAIFCheckBoxList
summary: API reference for SAIFCheckBoxList.
status: draft
owner: SAIF Documentation Team
last_reviewed: 2026-08-17
library: SAIF.Presentation.Web.Controls.V2
reference_type: package
---

# SAIFCheckBoxList

`SAIFCheckBoxList` is a `CheckBoxList` subclass extending the same read-only static-image rendering convention as `SAIFCheckBox` to an entire list of checkbox items, rendered as an HTML table ([BR-V2-003](../../business-rules.md#br-v2-003-read-only-input-controls-render-as-static-images-not-native-controls)).

## Purpose
- Provide a consistent "locked field" visual convention for checkbox lists (matching `SAIFCheckBox`'s single-item behavior) across the SAIF UI.
- Preserve each item's selection state across postbacks even while read-only, via a `ViewState`-tracked selection snapshot.

## Context
- Namespace: `SAIF.Presentation.Web.Controls.V2`
- Assembly/package: Compiled into `SAIF.BOF.Presentation.Web.Infragistics103`*

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| `[ReadOnly]` | `Property [ReadOnly] As Boolean` | Switches the control from its native interactive `CheckBoxList` rendering to a static `<table>` of checked/unchecked images and labels, per [BR-V2-003](../../business-rules.md#br-v2-003-read-only-input-controls-render-as-static-images-not-native-controls). |

## Inherited public members

`SAIFCheckBoxList` inherits from `CheckBoxList` (`System.Web.UI.WebControls`), a framework base class rather than a documented SAIF dependency library.

| Member | Signature | Purpose |
| --- | --- | --- |
| `AutoPostBack` | `Public Property AutoPostBack As Boolean` | Determines whether changing any item immediately posts the page back to the server. |
| `Items` | `Public ReadOnly Property Items As ListItemCollection` | Collection of selectable checkbox-list items managed by the control. |
| `RepeatColumns` | `Public Property RepeatColumns As Integer` | Controls how many item columns render before the layout wraps to a new row. |
| `RepeatDirection` | `Public Property RepeatDirection As RepeatDirection` | Controls whether items lay out horizontally or vertically. |
| `RepeatLayout` | `Public Property RepeatLayout As RepeatLayout` | Chooses the HTML layout pattern used to render the item list. |
| `SelectedIndex` | `Public Property SelectedIndex As Integer` | Index of the first selected item in the list. |
| `SelectedItem` | `Public ReadOnly Property SelectedItem As ListItem` | First currently selected item, useful when callers expect a primary selection. |
| `SelectedValue` | `Public Property SelectedValue As String` | Value of the first selected item. |
| `TextAlign` | `Public Property TextAlign As TextAlign` | Controls whether item labels render before or after their checkbox inputs. |
| `SelectedIndexChanged` | `Public Event SelectedIndexChanged As EventHandler` | Standard list-selection change event raised after postback. |

Standard `CheckBoxList`/`Control` members (`ID`, `ClientID`, `Controls`, `Visible`, `DataBind`, `FindControl`, etc.) are not re-documented here as they are unmodified framework behavior**.

## Behavioral notes
- `SAIFCheckBox_Init` snapshots each item's initial `Selected` state into `ViewState` on first load, so `SetChecked` can restore selections on later renders regardless of postback state changes.
- `RenderItems` lays items into `<tr>`/`<td>` cells honoring `RepeatDirection`/`RepeatColumns`, matching the base control's layout options even in read-only mode.
- `OnSelectedIndexChanged` re-syncs the `ViewState` selection snapshot when the list is editable, or restores it from `ViewState` when read-only.

## Constraints and usage notes
- The read-only image paths (`/Resources/Images/cb_checked.bmp`, `/Resources/Images/cb_unchecked.bmp`) are hardcoded and must exist in the hosting application.


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

## Sources
- SAIF.Presentation.Web.Controls.V2\SAIFCheckBoxList.vb