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**System capability**: SystemCapability.ArkUI.ArkUI.Full 36 37| Name | Type| Mandatory | Description| 38| --------| --------| ------ | -------- | 39| name | string | No| Name of the check box.<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.| 40| 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>**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| 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.| 42 43## Attributes 44 45In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 46 47### select 48 49select(value: boolean) 50 51Sets whether the check box is selected. 52 53Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). 54Since API version 18, this attribute supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters). 55 56**Widget capability**: This API can be used in ArkTS widgets since API version 9. 57 58**Atomic service API**: This API can be used in atomic services since API version 11. 59 60**System capability**: SystemCapability.ArkUI.ArkUI.Full 61 62**Parameters** 63 64| Name| Type | Mandatory| Description | 65| ------ | ------- | ---- | ------------------------------------------------------------ | 66| value | boolean | Yes | Whether the check box is selected.<br>Default value: **false**<br>**true**: The check box is selected. **false**: The check box is not selected.| 67 68### select<sup>18+</sup> 69 70select(isSelected: Optional\<boolean>) 71 72Sets whether the check box is selected. Compared to [select](#select), this API supports the **undefined** type for the **isSelected** parameter. 73 74This attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). This attribute supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md). 75 76**Widget capability**: This API can be used in ArkTS widgets since API version 18. 77 78**Atomic service API**: This API can be used in atomic services since API version 18. 79 80**System capability**: SystemCapability.ArkUI.ArkUI.Full 81 82**Parameters** 83 84| Name | Type | Mandatory| Description | 85| ---------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 86| isSelected | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether the check box is selected.<br>If **isSelected** is set to **undefined**, the default value **false** is used.<br>**true**: The check box is selected. **false**: The check box is not selected.| 87 88### selectedColor 89 90selectedColor(value: ResourceColor) 91 92Sets the color of the check box when it is selected. 93 94**Widget capability**: This API can be used in ArkTS widgets since API version 9. 95 96**Atomic service API**: This API can be used in atomic services since API version 11. 97 98**System capability**: SystemCapability.ArkUI.ArkUI.Full 99 100**Parameters** 101 102| Name| Type | Mandatory| Description | 103| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 104| 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.| 105 106### selectedColor<sup>18+</sup> 107 108selectedColor(resColor: Optional\<ResourceColor>) 109 110Sets the color of the check box when it is selected. Compared to [selectedColor](#selectedcolor), this API supports the **undefined** type for the **resColor** parameter. 111 112**Widget capability**: This API can be used in ArkTS widgets since API version 18. 113 114**Atomic service API**: This API can be used in atomic services since API version 18. 115 116**System capability**: SystemCapability.ArkUI.ArkUI.Full 117 118**Parameters** 119 120| Name | Type | Mandatory| Description | 121| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 122| resColor | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[ResourceColor](ts-types.md#resourcecolor)> | Yes | Color of the check box when it is selected.<br>If **resColor** is set to **undefined**, the default value **$r('sys.color.ohos_id_color_text_primary_activated')** is used.<br>An invalid value is handled as the default value.| 123 124### unselectedColor<sup>10+</sup> 125 126unselectedColor(value: ResourceColor) 127 128Sets the border color of the check box when it is not selected. 129 130**Atomic service API**: This API can be used in atomic services since API version 11. 131 132**System capability**: SystemCapability.ArkUI.ArkUI.Full 133 134**Parameters** 135 136| Name| Type | Mandatory| Description | 137| ------ | ------------------------------------------ | ---- | -------------------------- | 138| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Border color of the check box when it is not selected.<br>Default value: **$r('sys.color.ohos_id_color_switch_outline_off')**| 139 140### unselectedColor<sup>18+</sup> 141 142unselectedColor(resColor: Optional\<ResourceColor>) 143 144Sets the border color of the check box when it is not selected. Compared to [unselectedColor](#unselectedcolor10)<sup>10+</sup>, this API supports the **undefined** type for the **resColor** parameter. 145 146**Atomic service API**: This API can be used in atomic services since API version 18. 147 148**System capability**: SystemCapability.ArkUI.ArkUI.Full 149 150**Parameters** 151 152| Name | Type | Mandatory| Description | 153| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 154| resColor | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[ResourceColor](ts-types.md#resourcecolor)> | Yes | Border color of the check box when it is not selected.<br>If **resColor** is set to **undefined**, the default value **$r('sys.color.ohos_id_color_switch_outline_off')** is used.| 155 156### mark<sup>10+</sup> 157 158mark(value: MarkStyle) 159 160Sets the check mark style of the check box. 161 162**Atomic service API**: This API can be used in atomic services since API version 11. 163 164**System capability**: SystemCapability.ArkUI.ArkUI.Full 165 166**Parameters** 167 168| Name| Type | Mandatory| Description | 169| ------ | -------------------------------------------- | ---- | ------------------------------------------------------------ | 170| value | [MarkStyle](ts-types.md#markstyle10) | Yes | Check mark style of the check box. Since API version 12, if **indicatorBuilder** is set, the style is determined by **indicatorBuilder**.<br>Default value: {<br>strokeColor : `$r('sys.color.ohos_id_color_foreground_contrary')`,<br>strokeWidth: `$r('sys.float.ohos_id_checkbox_stroke_width')`,<br>size: '20vp'<br>} | 171 172### mark<sup>18+</sup> 173 174mark(style: Optional\<MarkStyle>) 175 176Sets the check mark style of the check box. Compared to [mark](#mark10)<sup>10+</sup>, this API supports the **undefined** type for the **style** parameter. 177 178**Atomic service API**: This API can be used in atomic services since API version 18. 179 180**System capability**: SystemCapability.ArkUI.ArkUI.Full 181 182**Parameters** 183 184| Name| Type | Mandatory| Description | 185| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 186| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[MarkStyle](ts-types.md#markstyle10)> | Yes | Check mark style of the check box. If **indicatorBuilder** is set, the style is determined by **indicatorBuilder**.<br>If **style** is set to **undefined**, the default value is used: {<br>strokeColor : `$r('sys.color.ohos_id_color_foreground_contrary')`,<br>strokeWidth: `$r('sys.float.ohos_id_checkbox_stroke_width')`,<br>size: '20vp'<br>} | 187 188### shape<sup>11+</sup> 189 190shape(value: CheckBoxShape) 191 192Sets the shape of the check box. 193 194**Widget capability**: This API can be used in ArkTS widgets since API version 11. 195 196**Atomic service API**: This API can be used in atomic services since API version 12. 197 198**System capability**: SystemCapability.ArkUI.ArkUI.Full 199 200**Parameters** 201 202| Name| Type | Mandatory| Description | 203| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 204| value | [CheckBoxShape](ts-appendix-enums.md#checkboxshape11) | Yes | Shape of the check box.<br>Default value: **CheckBoxShape.CIRCLE**| 205 206### shape<sup>18+</sup> 207 208shape(shape: Optional\<CheckBoxShape>) 209 210Sets the shape of the check box. Compared to [shape](#shape11)<sup>11+</sup>, this API supports the **undefined** type for the **shape** parameter. 211 212**Widget capability**: This API can be used in ArkTS widgets since API version 18. 213 214**Atomic service API**: This API can be used in atomic services since API version 18. 215 216**System capability**: SystemCapability.ArkUI.ArkUI.Full 217 218**Parameters** 219 220| Name| Type | Mandatory| Description | 221| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 222| shape | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CheckBoxShape](ts-appendix-enums.md#checkboxshape11)> | Yes | Shape of the check box.<br>If **shape** is set to **undefined**, the default value **CheckBoxShape.CIRCLE** is used.| 223 224### contentModifier<sup>12+</sup> 225 226contentModifier(modifier: ContentModifier\<CheckBoxConfiguration>) 227 228Creates a content modifier. 229 230**Atomic service API**: This API can be used in atomic services since API version 12. 231 232**System capability**: SystemCapability.ArkUI.ArkUI.Full 233 234**Parameters** 235 236| Name| Type | Mandatory| Description | 237| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 238| 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.| 239 240### contentModifier<sup>18+</sup> 241 242contentModifier(modifier: Optional<ContentModifier\<CheckBoxConfiguration>>) 243 244Creates a content modifier. Compared to [contentModifier](#contentmodifier12)<sup>12+</sup>, this API supports the **undefined** type for the **modifier** parameter. 245 246**Atomic service API**: This API can be used in atomic services since API version 18. 247 248**System capability**: SystemCapability.ArkUI.ArkUI.Full 249 250**Parameters** 251 252| Name | Type | Mandatory| Description | 253| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 254| modifier | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[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.<br>If **modifier** is set to **undefined**, no content modifier is used.| 255 256## Events 257 258In addition to the [universal events](ts-component-general-events.md), the following events are supported. 259 260### onChange 261 262onChange(callback: OnCheckboxChangeCallback) 263 264Invoked when the selected state of the check box changes. 265 266**Widget capability**: This API can be used in ArkTS widgets since API version 9. 267 268**Atomic service API**: This API can be used in atomic services since API version 11. 269 270**System capability**: SystemCapability.ArkUI.ArkUI.Full 271 272**Parameters** 273 274| Name | Type | Mandatory| Description | 275| -------- | ------------------------------------------------------- | ---- | ---------------- | 276| callback | [OnCheckboxChangeCallback](#oncheckboxchangecallback18) | Yes | Callback used to return the selected state.| 277 278### onChange<sup>18+</sup> 279 280onChange(callback: Optional\<OnCheckboxChangeCallback>) 281 282Invoked when the selected state of the check box changes. Compared to [onChange](#onchange), this API supports the **undefined** type for the **callback** parameter. 283 284**Widget capability**: This API can be used in ArkTS widgets since API version 18. 285 286**Atomic service API**: This API can be used in atomic services since API version 18. 287 288**System capability**: SystemCapability.ArkUI.ArkUI.Full 289 290**Parameters** 291 292| Name | Type | Mandatory| Description | 293| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 294| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[OnCheckboxChangeCallback](#oncheckboxchangecallback18)> | Yes | Callback used to return the selected state.<br>If **callback** is set to **undefined**, the callback function is not used.| 295 296## OnCheckboxChangeCallback<sup>18+</sup> 297 298type OnCheckboxChangeCallback = (value: boolean) => void 299 300Represents the callback invoked when the selected state of the check box changes. 301 302**Widget capability**: This API can be used in ArkTS widgets since API version 18. 303 304**Atomic service API**: This API can be used in atomic services since API version 18. 305 306**System capability**: SystemCapability.ArkUI.ArkUI.Full 307 308**Parameters** 309 310| Name| Type | Mandatory| Description | 311| ------ | ------- | ---- | ------------------------------------------------- | 312| value | boolean | Yes | Whether the check box is selected. The value **true** means that the check box is selected, and **false** means the opposite.| 313 314## CheckBoxConfiguration<sup>12+</sup> 315 316You need a custom class to implement the **ContentModifier** API. 317 318**Atomic service API**: This API can be used in atomic services since API version 12. 319 320**System capability**: SystemCapability.ArkUI.ArkUI.Full 321 322| Name| Type | Read Only | Optional | Description | 323| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 324| name | string | No| No|Name of the check box.| 325| selected | boolean| No| No| 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.| 326| triggerChange |Callback\<boolean>| No| No|Changes the selected state of the check box.<br>The value **true** means that the check box changes from unselected to selected, and **false** means that the check box changes from selected to unselected.| 327 328## Example 329 330### Example 1: Setting the Check Box Shape 331 332This example shows how to set **CheckBoxShape** to implement check boxes in circle and rounded square shapes. 333 334```ts 335// xxx.ets 336@Entry 337@Component 338struct CheckboxExample { 339 build() { 340 Flex({ justifyContent: FlexAlign.SpaceEvenly }) { 341 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 342 .select(true) 343 .selectedColor(0xed6f21) 344 .shape(CheckBoxShape.CIRCLE) 345 .onChange((value: boolean) => { 346 console.info('Checkbox1 change is' + value) 347 }) 348 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 349 .select(false) 350 .selectedColor(0x39a2db) 351 .shape(CheckBoxShape.ROUNDED_SQUARE) 352 .onChange((value: boolean) => { 353 console.info('Checkbox2 change is' + value) 354 }) 355 } 356 } 357} 358``` 359 360 361 362 363### Example 2: Setting the Check Box Color 364 365This example demonstrates how to set **mark** to customize the color of a check box. 366 367```ts 368// xxx.ets 369@Entry 370@Component 371struct Index { 372 373 build() { 374 Row() { 375 Column() { 376 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 377 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 378 .selectedColor(0x39a2db) 379 .shape(CheckBoxShape.ROUNDED_SQUARE) 380 .onChange((value: boolean) => { 381 console.info('Checkbox1 change is'+ value) 382 }) 383 .mark({ 384 strokeColor:Color.Black, 385 size: 50, 386 strokeWidth: 5 387 }) 388 .unselectedColor(Color.Red) 389 .width(30) 390 .height(30) 391 Text('Checkbox1').fontSize(20) 392 } 393 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 394 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 395 .selectedColor(0x39a2db) 396 .shape(CheckBoxShape.ROUNDED_SQUARE) 397 .onChange((value: boolean) => { 398 console.info('Checkbox2 change is' + value) 399 }) 400 .width(30) 401 .height(30) 402 Text('Checkbox2').fontSize(20) 403 } 404 } 405 .width('100%') 406 } 407 .height('100%') 408 } 409} 410``` 411 412 413 414 415### Example 3: Customizing the Check Box Style 416This 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." 417 418```ts 419// xxx.ets 420class MyCheckboxStyle implements ContentModifier<CheckBoxConfiguration> { 421 selectedColor: Color = Color.White 422 constructor(selectedColor: Color) { 423 this.selectedColor = selectedColor; 424 } 425 applyContent() : WrappedBuilder<[CheckBoxConfiguration]> 426 { 427 return wrapBuilder(buildCheckbox) 428 } 429} 430 431@Builder function buildCheckbox(config: CheckBoxConfiguration) { 432 Column({space:10}) { 433 Text(config.name + (config.selected ? "(Selected)" : " (Unselected)")).margin({right : 70, top : 50}) 434 Text(config.enabled ? "enabled true" : "enabled false").margin({right : 110}) 435 Shape() { 436 Path().width(100).height(100).commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z').fillOpacity(0).strokeWidth(3).onClick(()=>{ 437 if (config.selected) { 438 config.triggerChange(false) 439 } else { 440 config.triggerChange(true) 441 } 442 }).opacity(config.enabled ? 1 : 0.1) 443 Path().width(10).height(10).commands('M50 0 L100 100 L0 100 Z') 444 .visibility(config.selected ? Visibility.Visible : Visibility.Hidden) 445 .fill(config.selected ? (config.contentModifier as MyCheckboxStyle).selectedColor : Color.Black) 446 .stroke((config.contentModifier as MyCheckboxStyle).selectedColor) 447 .margin({left:10,top:10}) 448 .opacity(config.enabled ? 1 : 0.1) 449 } 450 .width(300) 451 .height(200) 452 .viewPort({ x: 0, y: 0, width: 310, height: 310 }) 453 .strokeLineJoin(LineJoinStyle.Miter) 454 .strokeMiterLimit(5) 455 .margin({left:50}) 456 } 457} 458 459@Entry 460@Component 461struct Index { 462 @State checkboxEnabled: boolean = true; 463 build() { 464 Column({ space: 100 }) { 465 Checkbox({ name: 'Check box status', group: 'checkboxGroup' }) 466 .contentModifier(new MyCheckboxStyle(Color.Red)) 467 .onChange((value: boolean) => { 468 console.info('Checkbox change is' + value) 469 }).enabled(this.checkboxEnabled) 470 471 Row() { 472 Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => { 473 if (value) { 474 this.checkboxEnabled = true 475 } else { 476 this.checkboxEnabled = false 477 } 478 }) 479 }.position({ x: 50, y: 130 }) 480 }.margin({top : 30}) 481 } 482} 483``` 484 485 486 487 488### Example 4: Setting the Text Check Box Style 489This example configures the selected style of a check box to display as text using the **indicatorBuilder** property. 490```ts 491// xxx.ets 492@Entry 493@Component 494struct CheckboxExample { 495 @Builder 496 indicatorBuilder(value: number) { 497 Column(){ 498 Text(value > 99 ? '99+': value.toString()) 499 .textAlign(TextAlign.Center) 500 .fontSize(value > 99 ? '16vp': '20vp') 501 .fontWeight(FontWeight.Medium) 502 .fontColor('#ffffffff') 503 } 504 } 505 build() { 506 Row() { 507 Column() { 508 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center}) { 509 Checkbox({ name: 'checkbox1', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(9)}}) 510 .shape(CheckBoxShape.CIRCLE) 511 .onChange((value: boolean) => { 512 console.info('Checkbox1 change is'+ value) 513 }) 514 .mark({ 515 strokeColor:Color.Black, 516 size: 50, 517 strokeWidth: 5 518 }) 519 .width(30) 520 .height(30) 521 Text('Checkbox1').fontSize(20) 522 }.padding(15) 523 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 524 Checkbox({ name: 'checkbox2', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(100)}}) 525 .shape(CheckBoxShape.ROUNDED_SQUARE) 526 .onChange((value: boolean) => { 527 console.info('Checkbox2 change is' + value) 528 }) 529 .width(30) 530 .height(30) 531 Text('Checkbox2').fontSize(20) 532 } 533 } 534 .width('100%') 535 } 536 .height('100%') 537 } 538} 539``` 540 541 542 543
