# Switch

The **Switch** widget is a small, interactive **toggle control** that lets users quickly turn a setting **on** or **off**.\
It represents a **binary choice** (true/false, enabled/disabled) in a compact, touch-friendly UI.

{% embed url="<https://youtu.be/x6K-jcK1AUs?si=gjiRQIANgb_wG72A>" %}

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

#### Adding a Switch Widget

The Switch 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-867fc2483262cd469fec292bae50c99276c530d1%2Fswitch.png?alt=media" alt="A hero image showing a switch widget in on and off states with customizable styling."><figcaption><p>The Switch widget provides intuitive binary toggle controls for settings and preferences.</p></figcaption></figure>

### **Core Concepts**

* **Two-State Control (On/Off)**\
  The Switch has only **two states**:
  * `true` → ON
  * `false` → OFF
* **Thumb & Track**\
  Visually, the Switch has:

  * A **thumb** → small circular handle that slides left/right
  * A **track** → the background path behind the thumb

  You can style both for **active** (on) and **inactive** (off) states.
* **Enabled vs Disabled**
  * When `enabled` is `false`, the Switch:
    * Can’t be interacted with
    * Typically appears visually dimmed/disabled
  * Useful when:
    * A setting depends on another toggle
    * A feature is locked/unavailable
* **Binding to State**\
  The `value` property is usually **bound to some state or variable** in your app.\
  When the user toggles the Switch, your logic updates that state and applies the change.

### Properties

| Property             | Description                                                                                                                                                                                                                  |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`            | If `false`, the Switch is disabled and cannot be interacted with. Use this when the setting is not currently applicable or is controlled elsewhere.                                                                          |
| `value`              | A boolean that determines the current state of the Switch: `true` for ON, `false` for OFF. Usually bound to app state or a setting value.                                                                                    |
| `activeColor`        | The color of the Switch’s **thumb** when it is in the ON state. Helps visually indicate that the setting is enabled.                                                                                                         |
| `inactiveThumbColor` | The color of the Switch’s **thumb** when it is in the OFF state. Typically a neutral or subdued color.                                                                                                                       |
| `activeTrackColor`   | The color of the **track** when the Switch is ON. Often a brand or accent color.                                                                                                                                             |
| `inactiveTrackColor` | The color of the **track** when the Switch is OFF. Usually a muted/grey tone.                                                                                                                                                |
| `onChanged`          | Action or callback that is triggered whenever the user toggles the switch. Receives an object with the new value: `{ 'value': value }`. Use this to update state, save settings, or run side effects when the value changes. |

### Default Properties

The Switch widget supports the following sections of [default-properties](https://docs.digia.tech/ui-building-blocks/widgets/default-properties "mention"):

**Layout**

* `width`
* `height`
* `padding`
* `margin`

**Alignment**

* `align`

**Visibility**

* `visible`

### **Use Cases**

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

* Enable/disable a **feature or preference**, such as:
  * Notifications on/off
  * Dark Mode on/off
  * Location access on/off
  * Auto-play videos on/off
* Control **binary settings** in:
  * Profile or app settings screens
  * Privacy & permission toggles
  * Feature flags inside experimental UIs

It’s best for **immediate, reversible changes**—where the result of toggling is clear to the user.