# Checkbox

The `Checkbox` is similar to the [Switch](https://docs.uify.io/component-reference/switch) component, offering the user to make a "Yes or No" decision, but using a checkbox as the UI element instead of a toggle.

![](https://1582137130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTYtq8XZyg79paoHbd93%2Fuploads%2FnLUUiBxpxAqMn4CwycAw%2Fimage.png?alt=media\&token=528ebda4-5a50-4682-b149-46cdff711ce3)

### Properties

The `Checkbox` component offers the following configuration properties.

<table><thead><tr><th width="158">Property</th><th width="159">Type</th><th width="161">Default value</th><th>Behavior</th></tr></thead><tbody><tr><td>Default value</td><td><code>boolean</code></td><td><code>false</code></td><td>Determines the initial state of the checkbox, and the state it will have when the <code>reset()</code> <a href="#api">API function</a> is used. When configured with a JS expression, it also updates the checkbox reactively when a dependency changes. <a href="../../writing-code/component-properties#reactivity">Learn more</a></td></tr><tr><td>Disabled</td><td><code>boolean</code></td><td><code>false</code></td><td>Whether the checkbox should be disabled. When disabled, the checkbox is greyed out and does not trigger the associated events.</td></tr><tr><td>Label</td><td><code>stringWithJs</code></td><td><code>'Checkbox'</code></td><td>Text displayed next to the checkbox.</td></tr><tr><td>Label alignment</td><td><code>'left' | 'center' | 'right'</code></td><td><code>'left'</code></td><td>Alignment of the label text.</td></tr><tr><td>Label position</td><td><code>'left' | 'right'</code></td><td><code>'left'</code></td><td>Whether the checkbox is rendered to the left of the label text, or to the right of it.</td></tr><tr><td>Required</td><td><code>boolean</code></td><td><code>false</code></td><td>Whether this checkbox must be active when a surrounding form is submitted. <a href="../form#submitting-a-form">Learn more about form submission</a></td></tr><tr><td>Toggle with label click</td><td><code>boolean</code></td><td><code>false</code></td><td>When set to <code>true</code>, the checkbox state is toggled when clicking on the label text as well. Otherwise, only a click on the checkbox itself changes its state.</td></tr></tbody></table>

### Events

The `Checkbox` offers three events related to changing its state. All of these events will only fire when the state changes due to UI events (i.e. user clicks), not when the checkbox state is changed programmatically. None of the associated actions will receive any [arguments](https://docs.uify.io/writing-code/actions/execution-model#action-arguments) when triggered.

* **On change run**: This action is triggered every time the checkbox value changes.
* **On false run**: This action is triggered when the checkbox value changes from `true` to `false`, i.e. when the user unchecks it.
* **On true run**: This action is triggered when the checkbox value changes from `false` to `true`, i.e. when the user checks it.

{% hint style="info" %}
"On false run" and "On true run" are triggered slightly earlier than "On change". They are however not executed in sequence, i.e. triggering the "On change" action does not wait or depend on the execution of "On false" or "On true". Due to this behavior, their executions might overlap.
{% endhint %}

### API

The `Checkbox` exposes the following API in the JavaScript runtime environment.

<table><thead><tr><th width="271">Property / Function</th><th width="210">Type</th><th>Behavior</th></tr></thead><tbody><tr><td><code>clear()</code></td><td><code>() => void</code></td><td>Clears the checkbox, i.e. sets its value to <code>false</code> and unchecks it visually.</td></tr><tr><td><code>disabled</code></td><td><code>boolean</code></td><td>Provides the current boolean value of the "Disabled" property.</td></tr><tr><td><code>label</code></td><td><code>string</code></td><td>Provides the current string value of the "Label" property.</td></tr><tr><td><code>reset()</code></td><td><code>() => void</code></td><td>Resets the checkbox state to the initial "Default value", i.e. it is set to the same state that it had after initial app load.</td></tr><tr><td><code>setDisabled(value)</code></td><td><code>(value: boolean) => void</code></td><td>Sets the value of the "Disabled" property to the provided boolean value.</td></tr><tr><td><code>setLabel(value)</code></td><td><code>(value: string) => void</code></td><td>Updates the value of the "Label" property to the provided string value.</td></tr><tr><td><code>setValue(value)</code></td><td><code>(value: boolean) => void</code></td><td>Sets the value of the checkbox to the provided boolean value. <code>true</code> checks it, <code>false</code> unchecks it. This does not trigger any actions associated with checkbox events.</td></tr><tr><td><code>value</code></td><td><code>boolean</code></td><td>Provides the current boolean value of the checkbox state. <code>true</code> in case the checkbox is checked, <code>false</code> otherwise.</td></tr></tbody></table>