# Check Box List Cell

A tutorial showing how to work with Check Box List cell types in SpreadJS, including the different customizations available

## Content

The CheckBoxList CellType renders a collection of selectable items within a single cell.
Each item is displayed as an independent checkbox, allowing multiple selections.
Unlike the single CheckBox CellType, CheckBoxList represents a collection of values rather than a single boolean state.
Three display modes are supported:

* `checkbox`
* `modern`
* `toggle`

![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.e110cf.png?width=600)

## Display Modes

The `mode` property controls the visual presentation of each item.

```javascript
cellType.mode(value);
```

Supported values:

```typescript
'checkbox' | 'modern' | 'toggle'
```

### Mode Capabilities

| Feature | checkbox | modern | toggle |
| ------- | -------- | ------ | ------ |
| Multi-selection | ✓ | ✓ | ✓ |
| Three-state | ✗ | ✗ | ✗ |
| Box Size | ✓ | ✓ | ✗ |
| toggleOptions | ✗ | ✗ | ✓ |
| TextAlign: inside | ✗ | ✗ | ✓ |

>type=note
> Three-state behavior is not supported in CheckBoxList.

## Selection Model

The CheckBoxList CellType supports multiple selections within a single cell.
The cell value is represented as an array containing the `value` field of each selected item.
Example:

```javascript
checkBoxListCellType.items([
  { text: "Price", value: "1749" },
  { text: "Usability", value: "5495496" }
]);
```

If both items are selected:

```javascript
sheet.getCell(1, 3).value();
// ["1749", "5495496"]
```

If no items are selected, the value is an empty array.
The type of each array element corresponds to the defined `value` of the item.

## Item Configuration

Items are defined using the `items()` method:

```javascript
cellType.items([
  { text: "Price", value: 1 },
  { text: "Usability", value: 2 }
]);
```

Each item includes:

* `text` – displayed label
* `value` – stored data value

## Layout Model

The layout of items within the cell is controlled by:

* `direction` (horizontal or vertical)
* `isFlowLayout`
* `maxRowCount`
* `maxColumnCount`
* `itemSpacing`

When `isFlowLayout` is enabled, items automatically wrap based on available cell space and layout direction.

## Text Alignment

The text alignment of each item is controlled using `textAlign`.
Supported values:

* `left`
* `right`
* `inside` (toggle mode only)

## Box Size

The size of each checkbox can be configured using `boxSize`.

* Accepts a number or `"auto"`
* Default size is 12 × 12
* Not available in toggle mode

## Toggle Mode Configuration

Toggle mode renders each item as a switch-style control.

```javascript
cellType.mode('toggle');
```

Additional appearance options are configured using `toggleOptions`:

```javascript
cellType.toggleOptions({
  width: 60,
  height: 30,
  trackColorOn: '#4CAF50',
  trackColorOff: '#767577',
  sliderColorOn: '#ffffff',
  sliderColorOff: '#ffffff',
  sliderMargin: 2,
  animationDuration: 100,
  trackRadius: 8,
  sliderRadius: 4
});
```

When `toggleOptions()` is called without parameters, it returns the current configuration.
In toggle mode:

* `boxSize` is not supported
* State changes require clicking the toggle control

## Using CheckBoxList in Designer

In Designer, a CheckBoxList can be applied by setting the cell type:
Home → Styles → Cell Editors → Cell Type → CheckBoxList
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.64712a.png?width=600)
After applying the cell type, configure items and layout options in the CellType dialog.
Right-click the cell and select **Edit CellType…**
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.729117.png?width=200)
This opens the CheckBox configuration dialog.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.9c799f.png?width=600)
When the mode is set to `toggle`, a different dialog is displayed.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.33a32a.png?width=600)