1# Checkbox 2 3**Checkbox** is a component that is used to enable or disable an option. 4 5> **NOTE** 6> 7> Since API version 11, the default style of the **Checkbox** component is changed from rounded square to circle. 8> 9> This component is supported since API version 8. Updates will be marked with a superscript to indicate their earliest API version. 10 11## Child Components 12 13Not supported 14 15## APIs 16 17Checkbox(options?: CheckboxOptions) 18 19Creates a check box. 20 21**Widget capability**: This API can be used in ArkTS widgets since API version 9. 22 23**Atomic service API**: This API can be used in atomic services since API version 11. 24 25**System capability**: SystemCapability.ArkUI.ArkUI.Full 26 27**Parameters** 28 29| Name | Type | Mandatory | Description | 30| ------- | ------------------------------------------- | ---- | ------------------ | 31| options | [CheckboxOptions](#checkboxoptions) | No | Check box parameters. | 32 33## CheckboxOptions 34 35| Name | Type | Mandatory | Description | 36| --------| --------| ------ | -------- | 37| name | string | No | Name of the check box.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 38| group | string | No | Group name of the check box (that is, the name of the check box group to which the check box belongs).<br>**NOTE**<br>For the settings to take effect, this parameter must be used with the [CheckboxGroup](ts-basic-components-checkboxgroup.md) component.<br>**Atomic service API**: This API can be used in atomic services since API version 11.| 39| indicatorBuilder<sup>12+</sup> | [CustomBuilder](ts-types.md#custombuilder8) | No | Custom component to indicate that the check box is selected. This custom component is center aligned with the check box. When **indicatorBuilder** is set to **undefined** or **null**, it defaults to the state where it is not set.<br>**Atomic service API**: This API can be used in atomic services since API version 12.| 40 41## Attributes 42 43In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported. 44 45### select 46 47select(value: boolean) 48 49Sets whether the check box is selected. 50 51Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). 52 53**Widget capability**: This API can be used in ArkTS widgets since API version 9. 54 55**Atomic service API**: This API can be used in atomic services since API version 11. 56 57**System capability**: SystemCapability.ArkUI.ArkUI.Full 58 59**Parameters** 60 61| Name | Type | Mandatory | Description | 62| ------ | ------- | ---- | ---------------------------------- | 63| value | boolean | Yes | Whether the check box is selected.<br>Default value: **false** | 64 65### selectedColor 66 67selectedColor(value: ResourceColor) 68 69Sets the color of the check box when it is selected. 70 71**Widget capability**: This API can be used in ArkTS widgets since API version 9. 72 73**Atomic service API**: This API can be used in atomic services since API version 11. 74 75**System capability**: SystemCapability.ArkUI.ArkUI.Full 76 77**Parameters** 78 79| Name | Type | Mandatory | Description | 80| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 81| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the check box when it is selected.<br>Default value: **$r('sys.color.ohos_id_color_text_primary_activated')**<br>An invalid value is handled as the default value. | 82 83### unselectedColor<sup>10+</sup> 84 85unselectedColor(value: ResourceColor) 86 87Sets the border color of the check box when it is not selected. 88 89**Atomic service API**: This API can be used in atomic services since API version 11. 90 91**System capability**: SystemCapability.ArkUI.ArkUI.Full 92 93**Parameters** 94 95| Name | Type | Mandatory | Description | 96| ------ | ------------------------------------------ | ---- | -------------------------- | 97| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Border color of the check box when it is not selected.<br>Default value: **'#33ffffff'** | 98 99### mark<sup>10+</sup> 100 101mark(value: MarkStyle) 102 103Sets the mark style of the check box. 104 105**Atomic service API**: This API can be used in atomic services since API version 11. 106 107**System capability**: SystemCapability.ArkUI.ArkUI.Full 108 109**Parameters** 110 111| Name | Type | Mandatory | Description | 112| ------ | --------------------------------- | ---- | -------------------- | 113| value | [MarkStyle](ts-types.md#markstyle10) | Yes | Mark style of the check box. Since API version 12, if **indicatorBuilder** is set, the content configured in **indicatorBuilder** will be displayed accordingly.| 114 115### shape<sup>11+</sup> 116 117shape(value: CheckBoxShape) 118 119Sets the shape of the check box. 120 121**Widget capability**: This API can be used in ArkTS widgets since API version 11. 122 123**Atomic service API**: This API can be used in atomic services since API version 12. 124 125**System capability**: SystemCapability.ArkUI.ArkUI.Full 126 127**Parameters** 128 129| Name | Type | Mandatory | Description | 130| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 131| value | [CheckBoxShape](#checkboxshape11) | Yes | Shape of the check box.<br>Default value: **CheckBoxShape.CIRCLE** | 132 133### contentModifier<sup>12+</sup> 134 135contentModifier(modifier: ContentModifier\<CheckBoxConfiguration>) 136 137Creates a content modifier. 138 139**Atomic service API**: This API can be used in atomic services since API version 12. 140 141**System capability**: SystemCapability.ArkUI.ArkUI.Full 142 143**Parameters** 144 145| Name | Type | Mandatory | Description | 146| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 147| modifier | [ContentModifier\<CheckBoxConfiguration>](#checkboxconfiguration12) | Yes | Content modifier to apply to the check box.<br>**modifier**: content modifier. You need a custom class to implement the **ContentModifier** API. | 148 149## Events 150 151In addition to the [universal events](ts-universal-events-click.md), the following attributes are supported. 152 153### onChange 154 155onChange(callback: (value: boolean) => void) 156 157Invoked when the selection status of the check box changes. 158 159**Widget capability**: This API can be used in ArkTS widgets since API version 9. 160 161**Atomic service API**: This API can be used in atomic services since API version 11. 162 163**System capability**: SystemCapability.ArkUI.ArkUI.Full 164 165**Parameters** 166 167| Name | Type | Mandatory | Description | 168| ------ | ------- | ---- | ------------------------------------------------- | 169| value | boolean | Yes | Whether the check box is selected. The value **true** means that the check box is selected, and **false** means the opposite. | 170 171## CheckBoxShape<sup>11+</sup> 172 173**Atomic service API**: This API can be used in atomic services since API version 12. 174 175| Name | Value | Description | 176| -------------- | ---- | -------- | 177| CIRCLE | 0 | Circle. | 178| ROUNDED_SQUARE | 1 | Rounded square. | 179 180## CheckBoxConfiguration<sup>12+</sup> 181 182You need a custom class to implement the **ContentModifier** API. 183 184**Atomic service API**: This API can be used in atomic services since API version 12. 185 186| Name | Type | Default Value | Description | 187| ------ | ------ | ------ |-------------------------------- | 188| name | string | - |Name of the check box. | 189| selected | boolean| false | Whether the check box is selected.<br>If the **select** attribute is not set, the default value **false** is used.<br>If the **select** attribute is set, the attribute value is used here. | 190| triggerChange |Callback\<boolean>| - |Changes the selected state of the check box. | 191 192## Example 193 194### Example 1 195 196```ts 197// xxx.ets 198@Entry 199@Component 200struct CheckboxExample { 201 build() { 202 Flex({ justifyContent: FlexAlign.SpaceAround }) { 203 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 204 .select(true) 205 .selectedColor(0xed6f21) 206 .shape(CheckBoxShape.CIRCLE) 207 .onChange((value: boolean) => { 208 console.info('Checkbox1 change is' + value) 209 }) 210 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 211 .select(false) 212 .selectedColor(0x39a2db) 213 .shape(CheckBoxShape.ROUNDED_SQUARE) 214 .onChange((value: boolean) => { 215 console.info('Checkbox2 change is' + value) 216 }) 217 } 218 } 219} 220``` 221 222 223 224 225### Example 2 226 227```ts 228// xxx.ets 229@Entry 230@Component 231struct Index { 232 233 build() { 234 Row() { 235 Column() { 236 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 237 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 238 .selectedColor(0x39a2db) 239 .shape(CheckBoxShape.ROUNDED_SQUARE) 240 .onChange((value: boolean) => { 241 console.info('Checkbox1 change is'+ value) 242 }) 243 .mark({ 244 strokeColor:Color.Black, 245 size: 50, 246 strokeWidth: 5 247 }) 248 .unselectedColor(Color.Red) 249 .width(30) 250 .height(30) 251 Text('Checkbox1').fontSize(20) 252 } 253 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 254 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 255 .selectedColor(0x39a2db) 256 .shape(CheckBoxShape.ROUNDED_SQUARE) 257 .onChange((value: boolean) => { 258 console.info('Checkbox2 change is' + value) 259 }) 260 .width(30) 261 .height(30) 262 Text('Checkbox2').fontSize(20) 263 } 264 } 265 .width('100%') 266 } 267 .height('100%') 268 } 269} 270``` 271 272 273 274 275### Example 3 276This example implements a custom check box. This check box comes in the custom pentagon style. When selected, the check box shows a red triangle pattern inside, and the title displays the word "Selected;" when deselected, the check box hides the red triangle pattern inside, and the title displays the word "Unselected." 277 278```ts 279// xxx.ets 280class MyCheckboxStyle implements ContentModifier<CheckBoxConfiguration> { 281 selectedColor: Color = Color.White 282 constructor(selectedColor: Color) { 283 this.selectedColor = selectedColor; 284 } 285 applyContent() : WrappedBuilder<[CheckBoxConfiguration]> 286 { 287 return wrapBuilder(buildCheckbox) 288 } 289} 290 291@Builder function buildCheckbox(config: CheckBoxConfiguration) { 292 Column({space:10}) { 293 Text(config.name + (config.selected ? " (Selected)" : " (Unselected)")).margin({right : 70, top : 50}) 294 Text(config.enabled ? "enabled true" : "enabled false").margin({right : 110}) 295 Shape() { 296 Path().width(100).height(100).commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z').fillOpacity(0).strokeWidth(3).onClick(()=>{ 297 if (config.selected) { 298 config.triggerChange(false) 299 } else { 300 config.triggerChange(true) 301 } 302 }).opacity(config.enabled ? 1 : 0.1) 303 Path().width(10).height(10).commands('M50 0 L100 100 L0 100 Z') 304 .visibility(config.selected ? Visibility.Visible : Visibility.Hidden) 305 .fill(config.selected ? (config.contentModifier as MyCheckboxStyle).selectedColor : Color.Black) 306 .stroke((config.contentModifier as MyCheckboxStyle).selectedColor) 307 .margin({left:11,top:10}) 308 .opacity(config.enabled ? 1 : 0.1) 309 } 310 .width(300) 311 .height(200) 312 .viewPort({ x: 0, y: 0, width: 310, height: 310 }) 313 .strokeLineJoin(LineJoinStyle.Miter) 314 .strokeMiterLimit(5) 315 .margin({left:50}) 316 } 317} 318 319@Entry 320@Component 321struct Index { 322 @State checkboxEnabled: boolean = true; 323 build() { 324 Column({ space: 100 }) { 325 Checkbox({ name: 'Check box status', group: 'checkboxGroup' }) 326 .contentModifier(new MyCheckboxStyle(Color.Red)) 327 .onChange((value: boolean) => { 328 console.info('Checkbox change is' + value) 329 }).enabled(this.checkboxEnabled) 330 331 Row() { 332 Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => { 333 if (value) { 334 this.checkboxEnabled = true 335 } else { 336 this.checkboxEnabled = false 337 } 338 }) 339 } 340 }.margin({top : 30}) 341 } 342} 343``` 344 345 346 347 348### Example 4 349In this example, a **Text** component is used to indicate that the check box is selected. 350```ts 351// xxx.ets 352@Entry 353@Component 354struct CheckboxExample { 355 @Builder 356 indicatorBuilder(value: number) { 357 Column(){ 358 Text(value > 99 ? '99+': value.toString()) 359 .textAlign(TextAlign.Center) 360 .fontSize(value > 99 ? '16vp': '20vp') 361 .fontWeight(FontWeight.Medium) 362 .fontColor('#ffffffff') 363 } 364 } 365 build() { 366 Row() { 367 Column() { 368 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center}) { 369 Checkbox({ name: 'checkbox1', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(9)}}) 370 .shape(CheckBoxShape.CIRCLE) 371 .onChange((value: boolean) => { 372 console.info('Checkbox1 change is'+ value) 373 }) 374 .mark({ 375 strokeColor:Color.Black, 376 size: 50, 377 strokeWidth: 5 378 }) 379 .width(30) 380 .height(30) 381 Text('Checkbox1').fontSize(20) 382 }.padding(15) 383 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 384 Checkbox({ name: 'checkbox2', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(100)}}) 385 .shape(CheckBoxShape.ROUNDED_SQUARE) 386 .onChange((value: boolean) => { 387 console.info('Checkbox2 change is' + value) 388 }) 389 .width(30) 390 .height(30) 391 Text('Checkbox2').fontSize(20) 392 } 393 } 394 .width('100%') 395 } 396 .height('100%') 397 } 398} 399``` 400 401 402 403
