# Switch

The `Switch` allows the user to make a basic "Yes or No" decision, i.e. it represents an input for a boolean value. This is useful either as part of a form, or as a stand-alone toggle for basic filters for tables and similar use cases.

<figure><img src="https://1582137130-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FkTYtq8XZyg79paoHbd93%2Fuploads%2FztliKHlFwCOZvh1w5mIB%2FScreen%20Cast%202022-10-20%20at%2011.56.21%20AM.gif?alt=media&#x26;token=e3252b8d-8623-43ca-ab67-92c6817862c4" alt=""><figcaption><p>Switch component</p></figcaption></figure>

### Properties

The `Switch` 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 whether the initial state of the switch should be active or not. If used with dynamic JavaScript expressions, this can reactively update the toggle based on specific conditions.</td></tr><tr><td>Disabled</td><td><code>boolean</code></td><td><code>false</code></td><td>Whether the switch should be disabled or not. When disabled, the input is greyed out and cannot be toggled.</td></tr><tr><td>Label</td><td><code>stringWithJs</code></td><td><code>'Switch'</code></td><td>Label that is rendered next to the toggle element.</td></tr><tr><td>Label alignment</td><td><code>'left' | 'center' | 'right'</code></td><td><code>'left'</code></td><td>Text alignment of the label.</td></tr><tr><td>Label position</td><td><code>'left' | 'right'</code></td><td><code>'left'</code></td><td>Determines whether the toggle should be placed to the left of the label or to the right.</td></tr><tr><td>Required</td><td><code>boolean</code></td><td><code>false</code></td><td>Determines how the switch behaves as part of a form during submit. When set to <code>true</code>, the surrounding form submit fails with a validation error in case the switch is not activated.</td></tr><tr><td>Toggle with label click</td><td><code>boolean</code></td><td><code>false</code></td><td>Determines whether the switch can be toggled only by clicking the toggle directly (<code>false</code>), or also by clicking on the label (<code>true</code>)</td></tr></tbody></table>

### Events

The `Switch` offers three events, that are all related to the UI event when the switch is toggled:

* **On change**: This event is triggered whenever the switch is toggled, regardless whether activated or deactivated.
* **On false**: This event is triggered whenever the switch is deactivated. This is equivalent to an action running at "On change", with a condition like `if (!mySwitch.value) { ... }` inside.
* **On true**: This event is triggered whenever the switch is activated. This is equivalent to an action running at "On change", with a condition like `if (mySwitch.value) { ... }` inside.

### API

The `Switch` 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>Resets the switch to inactive (<code>value</code> being <code>false</code>)</td></tr><tr><td> <code>disabled</code></td><td><code>boolean</code></td><td>Current boolean value of the "Disabled" property.</td></tr><tr><td><code>label</code></td><td><code>string</code></td><td>Current string value of the "Label" property.</td></tr><tr><td><code>reset()</code></td><td><code>() => void</code></td><td>Resets the switch similar to the <code>clear()</code> function, however not always to <code>false</code>, but to the value of the "Default value" property. This is usually used to reset a form to a default state, instead of completely clearing it.</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>Sets 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 toggle-state to the provided boolean value. This does not trigger any events.</td></tr><tr><td><code>value</code></td><td><code>boolean</code></td><td>Current boolean value representing the toggle-state of the switch. Will return <code>true</code> if active, and <code>false</code> if inactive.</td></tr></tbody></table>