# 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 CellType is an interactive, cell-embedded control that enables users to toggle binary states or tri-state modes within a worksheet.
It provides an Excel-compatible modern mode while preserving the legacy checkbox mode for backward compatibility.

* `checkbox` – classic square checkbox (default)
* `modern` – Excel-compatible rounded style
* `toggle` – switch-style toggle button

It also supports:

* Configurable interaction behavior
* Text wrapping and alignment control
* Excel import and export compatibility

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

## Display Modes

The `mode` property defines how the checkbox is rendered and behaves visually.

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

### Mode Comparison

|  | Classic Checkbox Mode | Modern Mode | Toggle Mode |
| --- | --------------------- | ----------- | ----------- |
| `mode` value | `"checkbox"` | `"modern"` | `"toggle"` |
| Border | 1px black, right angles | 2px, follows cell font color | Switch-style track |
| Corner Style | Right angle | Rounded | Rounded track |
| Color Behavior | Fixed black | Follows cell font color | Configurable via `toggleOptions` |
| Default Size (auto) | 8px(native size) | 15px (scaled with font size) | Controlled by `toggleOptions` |
| Background | White | Transparent (uses cell background color) | Track background |
| Indeterminate State | Green solid square | Follows font color (default black) | Not supported |
| `isThreeState` | Supported | Supported | Not supported |
| `textIndeterminate` | Supported | Supported | Not supported |
| `boxSize` | Supported | Supported | Not supported |
| Hover Cursor | Default | Pointer | Button interaction |
| Double-click Edit | Supported | Supported | Not supported |
| State Change Area | Controlled by `hitTestMode` | Controlled by `hitTestMode` | Toggle button only |

### Toggle Mode Configuration

Toggle mode provides additional appearance configuration through `toggleOptions`:

* `width` / `height`
* `autoSize`
* `sliderColorOn`, `sliderColorOff`
* `trackColorOn`, `trackColorOff`
* `animationDuration`
* `sliderMargin`
* `trackRadius`

When `autoSize: false` and `textAlign: inside`, `autoFitWidth` and `autoFitHeight` ignore text overflow and only consider the toggle button dimensions.

### Usage Examples

**Classic Checkbox Mode (Default)**

```javascript
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);
```

**Modern Mode**

```javascript
var cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.caption("Modern Checkbox");
cellType.mode("modern");
activeSheet.getCell(2, 1).cellType(cellType);
```

**Toggle Mode**

```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);
```

## Interaction Model

### Hit Testing (`hitTestMode`)

Specifies which area of the cell responds to mouse clicks.
Applies to `checkbox` and `modern` modes.

* `"cell"` (default) — the entire cell area responds to clicks
* `"checkbox"` — only the checkbox icon responds to clicks (Excel-compatible behavior)

>type=note
> The default value is `"cell"` for both `checkbox` and `modern` modes to preserve backward compatibility.

Use `"checkbox"` when you need behavior consistent with Microsoft Excel.

```javascript
var cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.textTrue("Yes");
cellType.textFalse("No");
cellType.hitTestMode("checkbox");
activeSheet.getCell(1, 1).cellType(cellType);
```

### Text Editing (`textEditable`)

Determines whether the checkbox can enter text editing mode (double-click or F2).
Applies to `checkbox` and `modern` modes.

* `true` (default) — text can be edited
* `false` — text editing is disabled

When set to `false`, the checkbox cannot enter edit mode.

```javascript
var cellType = new GC.Spread.Sheets.CellTypes.CheckBox();
cellType.textTrue("Yes");
cellType.textFalse("No");
cellType.textEditable(false);
activeSheet.getCell(1, 1).cellType(cellType);
```

>type=note
> * In `checkbox` mode, edit mode uses the browser’s native checkbox rendering.
> * In `modern` mode, the checkbox keeps the modern visual style during editing.

## State Model

### Three-State Behavior

The checkbox can represent three states: checked, unchecked, and indeterminate.
To enable the indeterminate state, set:

```javascript
cellType.isThreeState(true);
```

Three-state behavior is supported in `checkbox` and `modern` modes.
It is not supported in `toggle` mode.

### Value Mapping

The checkbox state is determined by the cell value:

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

Use the `value` method to programmatically control the state.

## Layout and Text Wrapping

### wordWrap

If the caption text is longer than the available cell space, enable text wrapping on the cell.
The default value of `wordWrap` is `false`.

```javascript
cellType.caption("This is a very very long long text");

activeSheet.getCell(1, 1).cellType(cellType);
activeSheet.setRowHeight(1, 120);
activeSheet.setColumnWidth(1, 110);

// Enable wrapping
activeSheet.getCell(1, 1).wordWrap(true);
```

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

### Line Break Rule

When wrapping is enabled:

* Text is first broken at word boundaries.
* If necessary, words are further split to fit the available width.

### Vertical Alignment

When `wordWrap` is enabled, the checkbox and caption follow the cell’s vertical alignment:
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.e00ca0.png?width=400)

### Horizontal Alignment

The caption text follows the cell’s horizontal alignment. Only the caption text alignment changes.
![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.4852b3.png?width=400)

## Excel Import and Export

The CheckBox CellType supports importing and exporting Excel files.

### Import Behavior

When importing from Excel:

* If cell data is not `null`, `undefined`, `true`, or `false`, no checkbox is added.
* If cell data is `null` or `undefined`, the checkbox is set to three-state.
* Imported checkboxes use default size `"auto"`.
* If horizontal alignment is not `left`, `center`, or `right`, it is set to `center`.
* If vertical alignment is not `top`, `center`, or `bottom`, it is set to `bottom`.
* The checkbox `mode` is automatically set to `"modern"`.
* If a table column style contains a checkbox, the mode is automatically set to `"modern"` after import.

### Export Behavior

When exporting to Excel:

* All checkboxes can be exported.
* If the checkbox is in an indeterminate state, it is exported as unchecked.
* Caption and other data are not exported; only the checkbox state is described.
* Due to cell data, the exported Excel file may not display as a checkbox (for example, when the cell data is `"Spread"`), but the cell remains a checkbox-type cell.
* If horizontal alignment is not `left`, `center`, or `right`, it is exported as `left`.
* If vertical alignment is not `top`, `center`, or `bottom`, it is exported as `top`.

## Using CheckBox in Designer

In Designer, a CheckBox can be inserted in two ways:

1. Set Cell Type to CheckBox
2. Use the CheckBox command from the Ribbon

Both methods assign the CheckBox CellType to the selected cell, but they initialize the checkbox with different default settings.

### Insertion Methods

1. Set Cell Type to CheckBox
    Home → Styles → Cell Editors → Cell Type → CheckBox
    This method sets the selected cell’s type to checkBox.
    ![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260317.af7dac.png?width=800)
2. Insert from Ribbon Command
    Insert → Controls → CheckBox
    ![image](https://cdn.mescius.io/document-site-files/images/b2223940-43c2-44cf-8eda-f5ab9acd84f0/image-20260421.6c1379.png?width=800)
    This command directly inserts a CheckBox into the selected cell.

### Default Differences

Checkboxes inserted using the two methods have the following differences:

|  | Set Cell Type | Insert Command |
| --- | ------------- | -------------- |
| `mode` | `"checkbox"` | `"modern"` |
| Position | Vertically top-aligned, horizontally left-aligned | Vertically top-aligned, horizontally centered |
| Size | 12px × 12px | `auto` |
| Hit Test | Entire cell | Checkbox icon only |
| Text Editing | Can enter edit mode | Cannot enter edit mode |

>type=note
> Notes:
>
> * Both methods create a CheckBox CellType.
> * The difference lies in the default mode and interaction settings applied during insertion.

### Configuring CheckBox Properties

After a cell is set to the CheckBox CellType, you can configure its properties through the CheckBox 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.8bdd6a.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.e1fcd4.png?width=400)
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.3bef25.png?width=400)