> For the complete documentation index, see [llms.txt](https://docs.digia.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digia.tech/ui-building-blocks/widgets/input-interaction-widgets/checkbox.md).

# 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="/files/TUtmnIDyGYOE6q8RTqxk" 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](/ui-building-blocks/widgets/default-properties.md).

### 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).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.digia.tech/ui-building-blocks/widgets/input-interaction-widgets/checkbox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.