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: { type: ToggleType, isOn?: boolean })
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**Parameters**
23
24| Name| Type| Mandatory  | Description          |
25| ---- | ---------- | -----| -------------- |
26| type | [ToggleType](#toggletype) | Yes  | Type of the toggle.<br>Default value: **ToggleType.Switch**|
27| isOn | 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>Since API version 10, this parameter supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).|
28
29
30## ToggleType
31
32**Widget capability**: This API can be used in ArkTS widgets since API version 9.
33
34**Atomic service API**: This API can be used in atomic services since API version 11.
35
36| Name      | Description                |
37| -------- | ---------------- |
38| 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'}|
39| 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.      |
40| Switch   | Switch type.<br>**NOTE**<br>The default value of the universal attribute [margin](ts-universal-attributes-size.md) 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'}|
41
42## Attributes
43
44In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
45
46### selectedColor
47
48selectedColor(value: ResourceColor)
49
50Sets the background color of the component when it is turned on.
51
52**Widget capability**: This API can be used in ArkTS widgets since API version 9.
53
54**Atomic service API**: This API can be used in atomic services since API version 11.
55
56**System capability**: SystemCapability.ArkUI.ArkUI.Full
57
58**Parameters**
59
60| Name| Type                                      | Mandatory| Description                    |
61| ------ | ------------------------------------------ | ---- | ------------------------ |
62| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Background color of the component when it is turned on.<br>Default value: **'#ff007dff'**|
63
64### switchPointColor
65
66switchPointColor(color: ResourceColor)
67
68Sets 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**.
69
70**Widget capability**: This API can be used in ArkTS widgets since API version 9.
71
72**Atomic service API**: This API can be used in atomic services since API version 11.
73
74**System capability**: SystemCapability.ArkUI.ArkUI.Full
75
76**Parameters**
77
78| Name| Type                                      | Mandatory| Description                      |
79| ------ | ------------------------------------------ | ---- | -------------------------- |
80| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Color of the circular slider when the component is of the **Switch** type.<br>Default value: **'#ffffffff'**|
81
82### switchStyle<sup>12+</sup>
83
84switchStyle(value: SwitchStyle)
85
86Sets the style for the component of the **Switch** type. This attribute is valid only when **type** is set to **ToggleType.Switch**.
87
88**System capability**: SystemCapability.ArkUI.ArkUI.Full
89
90**Parameters**
91
92| Name| Type                                               | Mandatory| Description            |
93| ------ | --------------------------------------------------- | ---- | ---------------- |
94| value  | [SwitchStyle<sup>12+</sup>](#switchstyle12) | Yes | Style of the component of the **Switch** type.|
95
96### contentModifier<sup>12+</sup>
97
98contentModifier(modifier: ContentModifier\<ToggleConfiguration>)
99
100Creates a content modifier.
101
102**System capability**: SystemCapability.ArkUI.ArkUI.Full
103
104**Parameters**
105
106| Name| Type                                         | Mandatory| Description                                            |
107| ------ | --------------------------------------------- | ---- | ------------------------------------------------ |
108| 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.|
109
110## SwitchStyle<sup>12+</sup>
111
112| Name             | Type                                       | Mandatory| Description                                                        |
113| ----------------- | ------------------------------------------- | ---- | ------------------------------------------------------------ |
114| pointRadius       | number \|  [Resource](ts-types.md#resource) | No  | Radius of the circular slider when the component is of the **Switch** type.<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 vlaue 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)|
115| 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**|
116| pointColor        | [ResourceColor](ts-types.md#resourcecolor)  | No  | Color of the circular slider when the component is of the **Switch** type.<br>Default value: **'#FFFFFFFF'**   |
117| trackBorderRadius | number \|  [Resource](ts-types.md#resource) | No  | Radius of the slider track border corners when the component is of the **Switch** type.<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|
118
119## Events
120
121In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
122
123### onChange
124
125onChange(callback: (isOn: boolean) =&gt; void)
126
127Triggered when the toggle status changes.
128
129**Widget capability**: This API can be used in ArkTS widgets since API version 9.
130
131**Atomic service API**: This API can be used in atomic services since API version 11.
132
133**System capability**: SystemCapability.ArkUI.ArkUI.Full
134
135**Parameters**
136
137| Name| Type   | Mandatory| Description                                                        |
138| ------ | ------- | ---- | ------------------------------------------------------------ |
139| isOn   | boolean | Yes  | Whether the toggle is on.<br>**true**: The toggle changes from off to on. **false**: The toggle changes from on to off.|
140
141## ToggleConfiguration<sup>12+</sup>
142
143You need a custom class to implement the **ContentModifier** API.
144
145| Name | Type   |    Default Value     |  Description             |
146| ------ | ------ | ------ |-------------------------------- |
147| isOn   | boolean| false  | If the **isOn** attribute is not set, the default value **false** is used.<br>If the **isOn** attribute is set, the attribute value is used here.|
148| triggerChange |Callback\<boolean>| - |Triggers toggle status changes.|
149
150
151## Example
152
153### Example 1
154
155```ts
156// xxx.ets
157@Entry
158@Component
159struct ToggleExample {
160  build() {
161    Column({ space: 10 }) {
162      Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%')
163      Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
164        Toggle({ type: ToggleType.Switch, isOn: false })
165          .selectedColor('#007DFF')
166          .switchPointColor('#FFFFFF')
167          .onChange((isOn: boolean) => {
168            console.info('Component status:' + isOn)
169          })
170
171        Toggle({ type: ToggleType.Switch, isOn: true })
172          .selectedColor('#007DFF')
173          .switchPointColor('#FFFFFF')
174          .onChange((isOn: boolean) => {
175            console.info('Component status:' + isOn)
176          })
177      }
178
179      Text('type: Checkbox').fontSize(12).fontColor(0xcccccc).width('90%')
180      Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
181        Toggle({ type: ToggleType.Checkbox, isOn: false })
182          .size({ width: 20, height: 20 })
183          .selectedColor('#007DFF')
184          .onChange((isOn: boolean) => {
185            console.info('Component status:' + isOn)
186          })
187
188        Toggle({ type: ToggleType.Checkbox, isOn: true })
189          .size({ width: 20, height: 20 })
190          .selectedColor('#007DFF')
191          .onChange((isOn: boolean) => {
192            console.info('Component status:' + isOn)
193          })
194      }
195
196      Text('type: Button').fontSize(12).fontColor(0xcccccc).width('90%')
197      Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
198        Toggle({ type: ToggleType.Button, isOn: false }) {
199          Text('status button').fontColor('#182431').fontSize(12)
200        }.width(106)
201        .selectedColor('rgba(0,125,255,0.20)')
202        .onChange((isOn: boolean) => {
203          console.info('Component status:' + isOn)
204        })
205
206        Toggle({ type: ToggleType.Button, isOn: true }) {
207          Text('status button').fontColor('#182431').fontSize(12)
208        }.width(106)
209        .selectedColor('rgba(0,125,255,0.20)')
210        .onChange((isOn: boolean) => {
211          console.info('Component status:' + isOn)
212        })
213      }
214    }.width('100%').padding(24)
215  }
216}
217```
218
219![toggle](figures/toggle.gif)
220
221### Example 2
222
223This 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.
224
225```ts
226// xxx.ets
227@Entry
228@Component
229struct ToggleExample {
230  build() {
231    Column({ space: 10 }) {
232      Text('type: Switch').fontSize(12).fontColor(0xcccccc).width('90%')
233      Flex({ justifyContent: FlexAlign.SpaceEvenly, alignItems: ItemAlign.Center }) {
234        Toggle({ type: ToggleType.Switch, isOn: false })
235          .selectedColor('#007DFF')
236          .switchStyle({
237            pointRadius: 15,
238            trackBorderRadius: 10,
239            pointColor: '#D2B48C',
240            unselectedColor: Color.Pink })
241          .onChange((isOn: boolean) => {
242            console.info('Component status:' + isOn)
243          })
244
245        Toggle({ type: ToggleType.Switch, isOn: true })
246          .selectedColor('#007DFF')
247          .switchStyle({
248            pointRadius: 15,
249            trackBorderRadius: 10,
250            pointColor: '#D2B48C',
251            unselectedColor: Color.Pink })
252          .onChange((isOn: boolean) => {
253            console.info('Component status:' + isOn)
254          })
255      }
256    }.width('100%').padding(24)
257  }
258}
259```
260
261![toggle](figures/toggleSwitchStyle.gif)
262
263### Example 3
264
265This 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.
266
267```ts
268// xxx.ets
269class MySwitchStyle implements ContentModifier<ToggleConfiguration> {
270  selectedColor: Color = Color.White
271  lamp: string = 'string';
272  constructor(selectedColor: Color, lamp: string) {
273    this.selectedColor = selectedColor
274    this.lamp = lamp;
275  }
276  applyContent() : WrappedBuilder<[ToggleConfiguration]>
277  {
278    return wrapBuilder(buildSwitch)
279  }
280}
281@Builder function buildSwitch(config: ToggleConfiguration) {
282  Column({ space: 50 }) {
283    Circle({ width: 150, height: 150 })
284      .fill(config.isOn ? (config.contentModifier as MySwitchStyle).selectedColor : Color.Blue)
285    Row() {
286      Button ('Blue '+ JSON.stringify((config.contentModifier as MySwitchStyle).lamp))
287        .onClick(() => {
288          config.triggerChange(false);
289        })
290      Button ('Yellow '+ JSON.stringify((config.contentModifier as MySwitchStyle).lamp))
291        .onClick(() => {
292          config.triggerChange(true);
293        })
294    }
295  }
296}
297
298@Entry
299@Component
300struct Index {
301  build() {
302    Column({ space: 50 }) {
303      Toggle({ type: ToggleType.Switch})
304        .enabled(true)
305        .contentModifier (new MySwitchStyle (Color.Yellow, 'light'))
306        .onChange((isOn: boolean) => {
307          console.info('Switch Log:' + isOn)
308        })
309    }.height('100%').width('100%')
310  }
311}
312```
313
314![toggle](figures/Toggle_builder.gif)
315