# Check Box Cell

A tutorial showing how to work with Check Box cell types in SpreadJS, including the different options available, such as alignment and wordwrap

## Content

The ​**​SpreadJS CheckBox​**​ is an interactive cell-embedded control that enables users to toggle binary states (checked/unchecked) or tri-state modes (including an indeterminate state) within spreadsheet applications. Designed to streamline data validation workflows and enhance user interaction, it replaces traditional dropdowns or radio buttons with intuitive visual markers.

## Basic Use

You can create and fully customize SpreadJS CheckBox cells using the [GC.Spread.Sheets.CellTypes.CheckBox](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.CellTypes.CheckBox "https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.CellTypes.CheckBox") class. This allows you to define appearance, manage state transitions (checked/unchecked/indeterminate), defining layout (`textAlign`) and adjust interactive behaviors through key properties like `textTrue`, `textFalse`, `isThreeState`, and `boxSize`.
Below is a practical example demonstrating how to instantiate and configure a CheckBox cell type with custom properties:

```javascript
//This example creates a check box cell.
var activeSheet = spread.getSheet(0);
var cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.caption("caption");
cellType.textTrue("true");
cellType.textFalse("false");
cellType.textIndeterminate("indeterminate");
cellType.textAlign(GC.Spread.Sheets.CellTypes.CheckBoxTextAlign.bottom);
cellType.boxSize(20);
activeSheet.getCell(1, 1).cellType(cellType);
```

![gif1](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/gif1.dcdd78.gif?width=200)

## **Indeterminate** State

SpreadJS CheckBox lets you enable tri-state functionality to represent checked, unchecked, and **indeterminate** states. Just use [isThreeState()](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.CellTypes.CheckBox#isthreestate "https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.CellTypes.CheckBox#isthreestate") to configure checkboxes for scenarios needing partial or undefined states.
![image](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/image.89191a.png?width=400)
You can set the state of the check box in code with the [value](/spreadjs/api/v18/classes/GC.Spread.Sheets.CellRange#value) method as shown in the following table:

| **Value** | **State** |
| ----- | ----- |
| `null ` | Indeterminate |
| `0 ` | Unchecked |
| `1 ` | Checked |

### Using Code

This example creates a check box cell with three states.

```javascript
// Get the activesheet
var activeSheet = spread.getSheet(0);
var cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.caption("caption");
cellType.textTrue("True");
cellType.textFalse("False");
cellType.textIndeterminate("Indeterminate");
cellType.textAlign(GC.Spread.Sheets.CellTypes.CheckBoxTextAlign.bottom);
cellType.isThreeState(true);
cellType.boxSize(20);
activeSheet.getCell(1, 1).cellType(cellType);
//activeSheet.getCell(1, 1).value(1);
```

![gif2](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/gif2.50419c.gif?width=200)

## Wrap Text

In the scenarios where the check box captions are too long to fit in a cell then to wrap the displayed text, you need to set the cell style **wordWrap** property to true. The **wordWrap** property is set to false by default.

```javascript
// set the long caption
cellType.caption("This is a very very long long text"); 
activeSheet.getCell(1, 1).cellType(cellType); 
activeSheet.setRowHeight(1, 120); 
activeSheet.setColumnWidth(1, 110); 
// set the wordwrap property to true
activeSheet.getCell(1, 1).wordWrap(true);
```

| **wordWrap property** | **Output** |
| ----------------- | ------ |
| **wordWrap** = false | ![wordWrap_false](https://cdn.mescius.io/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_false.a6ede2.PNG?width=200) |
| **wordWrap** = true | ![wordWrap_true](https://cdn.mescius.io/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_true.1db0f2.PNG?width=200) |

**Line Break Rule**
The line break rule followed in the check box cell is such that it initially breaks the content by words and, if necessary, further breaks the inner word to fit the available space.
![wordWrap_innerWordBreak](https://cdn.mescius.io/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_innerWordBreak.d51d01.PNG?width=200)
**Vertical Alignment**
If **wordWrap** in check box cell is enabled and the vertical alignment of the cell is set, then the check box will be displayed as below:

| **Vertical alignment** | **Output** |
| ------------------ | ------ |
| If cell vAlign is top, then the check box will align at the top with the text. | ![wordWrap_true](https://cdn.mescius.io/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_true.08d8f5.PNG?width=200) |
| If cell vAlign is middle, then the check box will align in the middle with the text. | ![wordWrap_middleAlign](https://cdn.mescius.io/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_middleAlign.f596f7.PNG?width=200) |
| If cell vAlign is bottom, then the check box will align at the bottom with the text. | ![wordWrap_bottomAlign](https://cdn.mescius.io/document-site-files/images/df1fe1ee-eb3c-4da7-8c20-a0d8d2b7e734/wordWrap_bottomAlign.f325dc.PNG?width=200) |

However, you can change the horizontal alignment of the wrapped text based on the cell’s hAlign value. For example, if the cell's hAlign is set to right, only the caption text will align to the right of the cell. Similarly, if cell's hAlign is set to left or center, only the caption text alignment is changed to left or center.

## Toggle Mode

You can transform standard checkboxes into interactive toggle switches via the [CheckBox.mode('toggle')](https://developer.mescius.com/spreadjs/api/classes/GC.Spread.Sheets.CellTypes.CheckBox#mode) method.
​**Key Features​​**​

* ​​**Customizable Appearance​​**
    Configure visual properties through the IToggleOptions interface:
    * ​​**Dimensions​​**: Set fixed `width/height` or enable `autoSize` for dynamic text scaling.
    * **​​Colors**​​: Define active (`sliderColorOn`, `trackColorOn`) and inactive (`sliderColorOff`, `trackColorOff`) states.
    * ​​**Animation​​**: Control transition smoothness with `animationDuration` (milliseconds).
    * ​​**Layout**​​: Adjust `sliderMargin` (spacing between slider and track) and `trackRadius` (corner rounding).
* ​​**Text Alignment​​**
    The CheckBoxTextAlign.inside option allows embedding text directly within the toggle button for space-efficient layouts, complementing the existing alignment options (top, bottom, left, right).

**Usage Constraints​**​

* **Disabled Properties​**​: In Toggle Mode, properties like `boxSize`, `isThreeState`, and `textIndeterminate` are ​**​unavailable​**​ and cannot be configured.
* ​**​Interaction Limits​**​: Double-click editing is ​**​disabled​**​; state changes occur ​**​only via toggle button clicks​**​ (not cell area clicks).
* ​**​Text Alignment​**​: When `autoSize: false` and `textAlign: inside`, `autoFitWidth`/`autoFitHeight` ​**​ignore text overflow​**​ and only consider the toggle button’s dimensions.

**Using Code**
This example implements toggle mode in the check box cell.

```javascript
const spread = new GC.Spread.Sheets.Workbook();
const sheet = spread.getActiveSheet();
const cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.textTrue('ON');
cellType.textFalse('OFF');
cellType.mode('toggle');
cellType.textAlign(GC.Spread.Sheets.CellTypes.CheckBoxTextAlign.inside);
cellType.toggleOptions({
  width: 65,
  height: 30,
  sliderMargin: 2,
  trackColorOn: '#8cbae8',
  trackColorOff: '#9e9e9e',
  sliderColorOn: '#1565c0',
  sliderColorOff: '#ffffff',
});
sheet.setCellType(0, 0, cellType);
```

![gif5](https://cdn.mescius.io/document-site-files/images/7719ad0a-f083-46d7-aff6-f63e2e187c15/gif5.fb3e46.gif?width=200)