---
description: >-
  Modify the appearance and behavior of the toggle switch’s thumb for enhanced
  user experience and aesthetics.
---

# Thumb Customization

## **Overview**

The `SiticoneToggleSwitch` allows developers to customize the **thumb** (the movable button inside the switch). By adjusting its **shape, color, size, and icons**, you can align the switch with your UI theme and user requirements.

***

### **1. Thumb Shape & Size Customization** 📐

| **Property**     | **Type**            | **Description**                                             |
| ---------------- | ------------------- | ----------------------------------------------------------- |
| `ThumbShape`     | `ControlThumbShape` | Defines the thumb’s geometric shape (`Circle` or `Square`). |
| `ExtraThumbSize` | `int`               | Adjusts the thumb size beyond the default size.             |

**Usage Example**

```csharp
myToggleSwitch.ThumbShape = SiticoneToggleSwitch.ControlThumbShape.Square;
myToggleSwitch.ExtraThumbSize = 4; // Makes the thumb larger
```

***

### **2. Thumb Color Customization** 🎨

| **Property**     | **Type** | **Description**                                 |
| ---------------- | -------- | ----------------------------------------------- |
| `OnThumbColor1`  | `Color`  | Primary gradient color of the thumb when ON.    |
| `OnThumbColor2`  | `Color`  | Secondary gradient color of the thumb when ON.  |
| `OffThumbColor1` | `Color`  | Primary gradient color of the thumb when OFF.   |
| `OffThumbColor2` | `Color`  | Secondary gradient color of the thumb when OFF. |

**Usage Example**

```csharp
myToggleSwitch.OnThumbColor1 = Color.LightGreen;
myToggleSwitch.OnThumbColor2 = Color.DarkGreen;
myToggleSwitch.OffThumbColor1 = Color.LightGray;
myToggleSwitch.OffThumbColor2 = Color.DarkGray;
```

***

### **3. Thumb Icon Customization** 🖼️

| **Property** | **Type** | **Description**                           |
| ------------ | -------- | ----------------------------------------- |
| `OnIcon`     | `Image`  | Icon displayed inside the thumb when ON.  |
| `OffIcon`    | `Image`  | Icon displayed inside the thumb when OFF. |

**Usage Example**

```csharp
myToggleSwitch.OnIcon = Image.FromFile("power_on.png");
myToggleSwitch.OffIcon = Image.FromFile("power_off.png");
```

***

### **4. When to Use These Features?** ✅

| **Feature**     | **Use Case**                                                     |
| --------------- | ---------------------------------------------------------------- |
| **Thumb Shape** | Adjust when a **square or rounded thumb** better matches the UI. |
| **Thumb Color** | Customize for **branding, dark/light themes, or visibility**.    |
| **Thumb Icons** | Use when **visual indicators** are needed for ON/OFF states.     |

***

### **5. Common Pitfalls & Design Considerations** 🛑

| **Pitfall**                     | **Cause**                                                | **Solution**                                                         |
| ------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------- |
| **Thumb not changing size**     | `ExtraThumbSize` not set                                 | Ensure `ExtraThumbSize` is greater than `0`.                         |
| **Icons not appearing**         | `OnIcon` or `OffIcon` not assigned                       | Assign valid images to `OnIcon` and `OffIcon`.                       |
| **Gradient colors not visible** | Identical values for `OnThumbColor1` and `OnThumbColor2` | Use different colors to achieve a **gradient effect**.               |
| **Thumb appears cropped**       | Thumb size too large                                     | Reduce `ExtraThumbSize` if the thumb overlaps the switch boundaries. |

***

### **6. Points Learned** 🎯

| **Point**                                       | **Description**                               |
| ----------------------------------------------- | --------------------------------------------- |
| **Thumb customization improves visual appeal.** | Helps align with branding and UI design.      |
| **Gradient colors add depth to the thumb.**     | Provides a **modern** and **dynamic** look.   |
| **Icons provide a quick state reference.**      | Users can easily **recognize ON/OFF states**. |

***

### **7. Review Checklist** ✔️

| **Item**                                               | **Check** |
| ------------------------------------------------------ | --------- |
| Is the **thumb shape** correct (`Circle` or `Square`)? | ✅         |
| Are the **thumb colors properly applied**?             | ✅         |
| Are **icons visible inside the thumb**?                | ✅         |
| Is the **thumb size appropriate** for the switch?      | ✅         |

***

### **8. Key Takeaways**

| **Key Takeaway**                                 | **Description**                                             |
| ------------------------------------------------ | ----------------------------------------------------------- |
| **Thumb customization enhances UI consistency.** | Helps **match the switch to the app’s design language**.    |
| **Icons provide quick, recognizable feedback.**  | Useful for **accessibility and intuitive toggling**.        |
| **Proper sizing prevents UI layout issues.**     | Ensures **the thumb does not overlap or appear too small**. |

***

### **9. Summary** 📌

#### **9.1 Feature Summary**

| **Feature**      | **Type** | **Description**                                 |
| ---------------- | -------- | ----------------------------------------------- |
| `ThumbShape`     | `enum`   | Defines if the thumb is a `Circle` or `Square`. |
| `ExtraThumbSize` | `int`    | Adjusts the thumb size.                         |
| `OnThumbColor1`  | `Color`  | Gradient start color when ON.                   |
| `OnThumbColor2`  | `Color`  | Gradient end color when ON.                     |
| `OffThumbColor1` | `Color`  | Gradient start color when OFF.                  |
| `OffThumbColor2` | `Color`  | Gradient end color when OFF.                    |
| `OnIcon`         | `Image`  | Icon displayed in ON state.                     |
| `OffIcon`        | `Image`  | Icon displayed in OFF state.                    |

#### **9.2 Key Benefits**

| **Benefit**                                          | **Description**                                         |
| ---------------------------------------------------- | ------------------------------------------------------- |
| **Provides a visually appealing toggle experience.** | Helps in **modern UI design**.                          |
| **Ensures better user feedback on state changes.**   | Users can **quickly identify ON/OFF status**.           |
| **Highly customizable for various applications.**    | Works well for **light/dark themes and accessibility**. |







