# Checkbox

The Checkbox widget is a visual control that allows a user to select or deselect a single option. It implements the Material Design specification for a checkbox, representing a binary choice that is typically independent of other choices (e.g., selecting multiple items in a list or toggling a setting on/off).

{% embed url="<https://youtu.be/H2OLYDApcIM?si=eRPRVXM0A6oOIE3i>" %}

Watch this on Youtube: <https://www.youtube.com/watch?v=H2OLYDApcIM>

#### Adding a Checkbox Widget

The Checkbox widget is located in the **Form Elements** section of the Widget Palette. Once added, you can configure its properties from the **Widget Properties Panel**.

<figure><img src="https://3626461507-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FbhApDTL7kHrXte2TTtjs%2Fuploads%2Fgit-blob-74867d21519bb1ae0292348bdf54dfa62123826f%2Fcheckbox_hero_image.png?alt=media" alt="A hero image showing various checkbox states and configurations."><figcaption><p>The Checkbox widget provides flexible binary selection controls.</p></figcaption></figure>

### Core Concepts

1. **Binary State**\
   The checkbox tracks a single **boolean value**:
   * `true` → checked / selected
   * `false` → unchecked / unselected
2. **Visual Feedback**\
   The state is shown by:
   * Background (active vs inactive)
   * Icon (checked vs unchecked)
   * Shape and border
3. **Independent Selection**\
   Each checkbox works **independently**, even if there are many in a list.\
   Users can select **any combination** of options.

### Properties

These properties define the widget's interaction, background, and overall dimensions.

| Property             | Description                                                                |
| -------------------- | -------------------------------------------------------------------------- |
| `value`              | The current state of the checkbox (true for checked, false for unchecked). |
| `size`               | The overall dimension (width/height) of the checkbox container.            |
| `activeBackground`   | Background color when the checkbox is active (value: true).                |
| `inactiveBackground` | Background color when the checkbox is inactive (value: false).             |
| `borderWidth`        | The thickness of the border when inactive.                                 |
| `shape`              | The container’s shape (e.g., rectangle or circle).                         |
| `borderRadius`       | The corner radius of the container (used for rectangle shape).             |

#### Active Icon Properties

These properties define the appearance of the icon when the `value` is `true` (checked).

| Property          | Description                                      |
| ----------------- | ------------------------------------------------ |
| `activeIcon`      | The icon displayed when the checkbox is checked. |
| `activeIconSize`  | The size of the active icon.                     |
| `activeIconColor` | The color of the active icon.                    |

#### Inactive Icon Properties

These properties define the appearance of the icon when the `value` is `false` (unchecked).

| Property            | Description                                        |
| ------------------- | -------------------------------------------------- |
| `inactiveIcon`      | The icon displayed when the checkbox is unchecked. |
| `inactiveIconSize`  | The size of the inactive icon.                     |
| `inactiveIconColor` | The color of the inactive icon.                    |

***

### **Icon Properties**

You can customize the icons used for the checked and unchecked states.

<table><thead><tr><th width="176.25390625">Property</th><th>Description</th></tr></thead><tbody><tr><td><code>Active Icon</code></td><td>The icon to display when the checkbox is checked. See <a data-mention href="https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/building-ui/widgets/input-interaction-widgets/icon.md">https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/building-ui/widgets/input-interaction-widgets/icon.md</a> for properties.</td></tr><tr><td><code>Inactive Icon</code></td><td>The icon to display when the checkbox is unchecked. See <a data-mention href="https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/building-ui/widgets/input-interaction-widgets/icon.md">https://github.com/Digia-Technology-Private-Limited/digiaDocs/blob/main/docs/building-ui/widgets/input-interaction-widgets/icon.md</a> for properties.</td></tr></tbody></table>

**Value Property with Expressions**

The **Value** property is particularly powerful as it accepts both static boolean values and dynamic expressions:

* **Static Values**: Set to `true` or `false` for fixed checkbox states
* **Expressions**: Use dynamic logic to control checkbox state based on:
  * User input from other form fields
  * Application state variables
  * Conditional logic based on user selections
  * Form validation results

**Example Use Cases:**

* Form validation: `isNotEmpty(user.email) && gte(length(user.password), 8)`
* Conditional agreements: `gte(user.age, 18)`

***

### Default Properties <a href="#default-properties" id="default-properties"></a>

The Checkbox widget supports all [default-properties](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention").

### Use Cases

Use a **Checkbox** when you want the user to:

* **Toggle a setting**
  * Enable/disable notifications
  * Turn features on/off (dark mode, sound, autosave)
* **Select multiple options in a list**
  * Choose multiple items (e.g., products, categories, filters)
  * Bulk-select rows in a table or list (“Select all”, “Select some”)
* **Confirm or agree**
  * “I agree to the Terms & Conditions”
  * “Remember this device” or “Save this preference”

Choose a Checkbox when the choice is **yes/no** and **doesn’t require only one option** (for that, radio buttons are better).