1# Toggle 2 3The **Toggle** component provides a clickable element in the check box, button, or switch type. 4 5> **NOTE** 6> 7> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 8 9## Child Components 10 11This component can contain child components only when **ToggleType** is set to **Button**. 12 13 14## APIs 15 16Toggle(options: ToggleOptions) 17 18**Widget capability**: This API can be used in ArkTS widgets since API version 9. 19 20**Atomic service API**: This API can be used in atomic services since API version 11. 21 22**System capability**: SystemCapability.ArkUI.ArkUI.Full 23 24**Parameters** 25 26| Name| Type| Mandatory | Description | 27| ---- | ---------- | -----| -------------- | 28| options | [ToggleOptions](#toggleoptions18) | Yes | Options of the toggle.| 29 30## ToggleOptions<sup>18+</sup> 31 32**Widget capability**: This API can be used in ArkTS widgets since API version 18. 33 34**Atomic service API**: This API can be used in atomic services since API version 18. 35 36**System capability**: SystemCapability.ArkUI.ArkUI.Full 37 38| Name | Type | Mandatory| Description | 39| ----------------- | --------------------------------- | ---- | ------------------------------------------------------------ | 40| type<sup>8+</sup> | [ToggleType](#toggletype) | Yes | Type of the toggle.<br>Default value: **ToggleType.Switch**<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 41| isOn<sup>8+</sup> | boolean | No | Whether the toggle is turned on. The value **true** means that the toggle is turned on, and **false** means the opposite.<br>Default value: **false**<br>This parameter supports two-way binding through [$$](../../../ui/state-management/arkts-two-way-sync.md).<br>This parameter supports two-way binding through the [!! syntax](../../../ui/state-management/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters).<br>**Widget capability**: This API can be used in ArkTS widgets since API version 9.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 42 43## ToggleType 44 45**Widget capability**: This API can be used in ArkTS widgets since API version 9. 46 47**Atomic service API**: This API can be used in atomic services since API version 11. 48 49**System capability**: SystemCapability.ArkUI.ArkUI.Full 50 51| Name | Description | 52| -------- | ------------------------------------------------------------ | 53| Checkbox | Check box type.<br>**NOTE**<br>Since API version 11, the default style of the **Checkbox** component is changed from rounded square to circle.<br>The default value of the universal attribute [margin](ts-universal-attributes-size.md#margin) is as follows:<br>{<br> top: '14px',<br> right: '14px',<br> bottom: '14px',<br> left: '14px'<br> }.<br>Default size:<br>{width:'20vp', height:'20vp'}| 54| Button | Button type. The set string, if any, will be displayed inside the button.<br>The default height is 28 vp, and there is no default width.| 55| Switch | Switch type.<br>**NOTE**<br>The default value of the universal attribute [margin](ts-universal-attributes-size.md#margin) is as follows:<br>{<br> top: '6px',<br> right: '14px',<br> bottom: '6px',<br> left: '14px'<br> }.<br>Default size:<br>{width:'36vp', height:'20vp'}| 56 57## Attributes 58 59In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 60 61### selectedColor 62 63selectedColor(value: ResourceColor) 64 65Sets the background color of the component when it is turned on. 66 67**Widget capability**: This API can be used in ArkTS widgets since API version 9. 68 69**Atomic service API**: This API can be used in atomic services since API version 11. 70 71**System capability**: SystemCapability.ArkUI.ArkUI.Full 72 73**Parameters** 74 75| Name| Type | Mandatory| Description | 76| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 77| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Background color of the component when it is turned on.<br>Default value:<br>When **ToggleType** is set to **Switch**, the default value is **$r('sys.color.ohos_id_color_component_activated')**.<br>When **ToggleType** is set to **Checkbox**, the default value is **$r('sys.color.ohos_id_color_component_activated')**.<br>When **ToggleType** is set to **Button**, the default value is **$r('sys.color.ohos_id_color_component_activated')** with the opacity of **$r('sys.color.ohos_id_color_text_highlight_bg')**.| 78 79### switchPointColor 80 81switchPointColor(color: ResourceColor) 82 83Sets the color of the circular slider when the component is of the **Switch** type. This attribute is valid only when **type** is set to **ToggleType.Switch**. 84 85**Widget capability**: This API can be used in ArkTS widgets since API version 9. 86 87**Atomic service API**: This API can be used in atomic services since API version 11. 88 89**System capability**: SystemCapability.ArkUI.ArkUI.Full 90 91**Parameters** 92 93| Name| Type | Mandatory| Description | 94| ------ | ------------------------------------------ | ---- | -------------------------- | 95| color | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the circular slider when the component is of the **Switch** type.<br>Default value: **$r('sys.color.ohos_id_color_foreground_contrary')**| 96 97### switchStyle<sup>12+</sup> 98 99switchStyle(value: SwitchStyle) 100 101Sets the style for the component of the **Switch** type. This attribute is valid only when **type** is set to **ToggleType.Switch**. 102 103**Atomic service API**: This API can be used in atomic services since API version 12. 104 105**System capability**: SystemCapability.ArkUI.ArkUI.Full 106 107**Parameters** 108 109| Name| Type | Mandatory| Description | 110| ------ | ------------------------------------- | ---- | ---------------- | 111| value | [SwitchStyle](#switchstyle12) | Yes | Style of the component of the **Switch** type.| 112 113### contentModifier<sup>12+</sup> 114 115contentModifier(modifier: ContentModifier\<ToggleConfiguration>) 116 117Creates a content modifier. 118 119**Atomic service API**: This API can be used in atomic services since API version 12. 120 121**System capability**: SystemCapability.ArkUI.ArkUI.Full 122 123**Parameters** 124 125| Name| Type | Mandatory| Description | 126| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 127| modifier | [ContentModifier\<ToggleConfiguration>](#toggleconfiguration12) | Yes | Content modifier to apply to the current component.<br>**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API.| 128 129## SwitchStyle<sup>12+</sup> 130 131**Atomic service API**: This API can be used in atomic services since API version 12. 132 133**System capability**: SystemCapability.ArkUI.ArkUI.Full 134 135| Name | Type | Mandatory| Description | 136| ----------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ | 137| pointRadius | number \| [Resource](ts-types.md#resource) | No | Radius of the circular slider when the component is of the **Switch** type. The unit is vp.<br>**NOTE**<br>This parameter cannot be set in percentage. The value specified is used only when it is greater than or equal to 0.<br>If the value is not specified or the specified one is less than 0, the radius is set using the following formula:<br>(Component height (in vp)/2) - (2 vp x Component height (in vp)/20 vp)| 138| unselectedColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the component when it is of the **Switch** type and is disabled.<br>Default value: **0x337F7F7F**| 139| pointColor | [ResourceColor](ts-types.md#resourcecolor) | No | Color of the circular slider when the component is of the **Switch** type.<br>Default value: **$r('sys.color.ohos_id_color_foreground_contrary')**| 140| trackBorderRadius | number \| [Resource](ts-types.md#resource) | No | Radius of the slider track border corners when the component is of the **Switch** type. The unit is vp.<br>**NOTE**<br>This parameter cannot be set in percentage. If the value specified is less than 0, the radius is set using the default value formula. If the value specified is greater than half of the component height, the latter is used. In other cases, the value specified is used.<br>If the value is not specified or the specified one is less than 0, the radius is set using the default value formula.<br>Default value formula: Component height (in vp)/2| 141 142## Events 143 144In addition to the [universal events](ts-component-general-events.md), the following events are supported. 145 146### onChange 147 148onChange(callback: (isOn: boolean) => void) 149 150Triggered when the toggle status changes. 151 152**Widget capability**: This API can be used in ArkTS widgets since API version 9. 153 154**Atomic service API**: This API can be used in atomic services since API version 11. 155 156**System capability**: SystemCapability.ArkUI.ArkUI.Full 157 158**Parameters** 159 160| Name| Type | Mandatory| Description | 161| ------ | ------- | ---- | ------------------------------------------------------------ | 162| isOn | boolean | Yes | Whether the toggle is on.<br>**true**: The toggle is on. **false**: The toggle is off.| 163 164## ToggleConfiguration<sup>12+</sup> 165 166You need a custom class to implement the **ContentModifier** API. 167 168**Atomic service API**: This API can be used in atomic services since API version 12. 169 170**System capability**: SystemCapability.ArkUI.ArkUI.Full 171 172| Name | Type | Read-Only | Optional | Description | 173| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 174| isOn | boolean| No | No| Whether the toggle is turned on.<br>Default value: **false**<br>The value **true** means that the toggle is turned on, and **false** means the opposite.| 175| enabled | boolean | No| No| Whether the toggle is enabled. When enabled, the toggle allows state switching.<br>Default value: **true**<br>The value **true** means that the toggle is enabled, and **false** means the opposite.| 176| triggerChange |Callback\<boolean>| No| No|Callback invoked when the toggle's state changes.<br>Whether the toggle is on.<br>**true**: The toggle is on. The value **true** means the state changes from off to on, and **false** means the state changes from on to off.| 177 178 179## Example 180 181### Example 1: Setting the Toggle Style 182 183This example demonstrates how to configure the style for different types of toggles (checkbox, switch, and button) using **ToggleType**. 184 185```ts 186// xxx.ets 187@Entry 188@Component 189struct ToggleExample { 190 build() { 191 Column({ space: 10 }) { 192 Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%') 193 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 194 Toggle({ type: ToggleType.Switch, isOn: false }) 195 .selectedColor('#007DFF') 196 .switchPointColor('#FFFFFF') 197 .onChange((isOn: boolean) => { 198 console.info('Component status:' + isOn); 199 }) 200 201 Toggle({ type: ToggleType.Switch, isOn: true }) 202 .selectedColor('#007DFF') 203 .switchPointColor('#FFFFFF') 204 .onChange((isOn: boolean) => { 205 console.info('Component status:' + isOn); 206 }) 207 } 208 209 Text('type: Checkbox').fontSize(12).fontColor(0xcccccc).width('90%') 210 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 211 Toggle({ type: ToggleType.Checkbox, isOn: false }) 212 .size({ width: 20, height: 20 }) 213 .selectedColor('#007DFF') 214 .onChange((isOn: boolean) => { 215 console.info('Component status:' + isOn); 216 }) 217 218 Toggle({ type: ToggleType.Checkbox, isOn: true }) 219 .size({ width: 20, height: 20 }) 220 .selectedColor('#007DFF') 221 .onChange((isOn: boolean) => { 222 console.info('Component status:' + isOn); 223 }) 224 } 225 226 Text('type: Button').fontSize(12).fontColor(0xcccccc).width('90%') 227 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 228 Toggle({ type: ToggleType.Button, isOn: false }) { 229 Text('status button').fontColor('#182431').fontSize(12) 230 }.width(106) 231 .selectedColor('rgba(0,125,255,0.20)') 232 .onChange((isOn: boolean) => { 233 console.info('Component status:' + isOn); 234 }) 235 236 Toggle({ type: ToggleType.Button, isOn: true }) { 237 Text('status button').fontColor('#182431').fontSize(12) 238 }.width(106) 239 .selectedColor('rgba(0,125,255,0.20)') 240 .onChange((isOn: boolean) => { 241 console.info('Component status:' + isOn); 242 }) 243 } 244 }.width('100%').padding(24) 245 } 246} 247``` 248 249 250 251### Example 2: Customizing the Toggle Style 252 253This example implements a toggle of the **Switch** type with custom settings, including the radius and color of the circular slider, background color in the off state, and radius of the slider track border corners. 254 255```ts 256// xxx.ets 257@Entry 258@Component 259struct ToggleExample { 260 build() { 261 Column({ space: 10 }) { 262 Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%') 263 Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) { 264 Toggle({ type: ToggleType.Switch, isOn: false }) 265 .selectedColor('#007DFF') 266 .switchStyle({ 267 pointRadius: 15, 268 trackBorderRadius: 10, 269 pointColor: '#D2B48C', 270 unselectedColor: Color.Pink }) 271 .onChange((isOn: boolean) => { 272 console.info('Component status:' + isOn); 273 }) 274 275 Toggle({ type: ToggleType.Switch, isOn: true }) 276 .selectedColor('#007DFF') 277 .switchStyle({ 278 pointRadius: 15, 279 trackBorderRadius: 10, 280 pointColor: '#D2B48C', 281 unselectedColor: Color.Pink }) 282 .onChange((isOn: boolean) => { 283 console.info('Component status:' + isOn); 284 }) 285 } 286 }.width('100%').padding(24) 287 } 288} 289``` 290 291 292 293### Example 3: Implementing a Custom Toggle Style 294 295This example implements a toggle in a custom style. When you click the **Blue** button, the circle background turns blue. When you click the **Yellow** button, the circle background turns yellow. 296 297```ts 298// xxx.ets 299class MySwitchStyle implements ContentModifier<ToggleConfiguration> { 300 selectedColor: Color = Color.White; 301 lamp: string = 'string'; 302 303 constructor(selectedColor: Color, lamp: string) { 304 this.selectedColor = selectedColor; 305 this.lamp = lamp; 306 } 307 308 applyContent(): WrappedBuilder<[ToggleConfiguration]> { 309 return wrapBuilder(buildSwitch); 310 } 311} 312 313@Builder 314function buildSwitch(config: ToggleConfiguration) { 315 Column({ space: 50 }) { 316 Circle({ width: 150, height: 150 }) 317 .fill(config.isOn ? (config.contentModifier as MySwitchStyle).selectedColor : Color.Blue) 318 Row() { 319 Button('Blue ' + JSON.stringify((config.contentModifier as MySwitchStyle).lamp)) 320 .onClick(() => { 321 config.triggerChange(false); 322 }) 323 Button('Yellow ' + JSON.stringify((config.contentModifier as MySwitchStyle).lamp)) 324 .onClick(() => { 325 config.triggerChange(true); 326 }) 327 } 328 } 329} 330 331@Entry 332@Component 333struct Index { 334 build() { 335 Column({ space: 50 }) { 336 Toggle({ type: ToggleType.Switch }) 337 .enabled(true) 338 .contentModifier(new MySwitchStyle(Color.Yellow, 'light')) 339 .onChange((isOn: boolean) => { 340 console.info('Switch Log:' + isOn); 341 }) 342 }.height('100%').width('100%') 343 } 344} 345``` 346 347 348
