1# CheckboxGroup 2 3The **CheckboxGroup** component is used to select or deselect all check boxes in a group. 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 11Not supported 12 13## APIs 14 15CheckboxGroup(options?: CheckboxGroupOptions) 16 17Creates a check box group so that you can select or deselect all check boxes in the group at once. Check boxes and check box groups that share the same group name belong to the same group. 18 19When this API is used with components that come with a pre-loading mechanism, such as the **List** component, those check boxes that have not been created yet need to be manually selected or unselected. 20 21**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 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 | [CheckboxGroupOptions](#checkboxgroupoptions) | No | Check box group parameters.| 32 33## CheckboxGroupOptions 34 35**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 36 37**Atomic service API**: This API can be used in atomic services since API version 11. 38 39**System capability**: SystemCapability.ArkUI.ArkUI.Full 40 41| Name| Type| Mandatory| Description| 42| -------- | -------- | -------- | -------- | 43| group | string | No| Group name.<br>**NOTE**<br>If there are multiple check box groups with the same group name, only the first check box group takes effect.| 44 45## Attributes 46 47In addition to the [universal attributes](ts-component-general-attributes.md), the following attributes are supported. 48 49### selectAll 50 51selectAll(value: boolean) 52 53Sets whether to select all. If the **select** attribute is set for a [Checkbox](ts-basic-components-checkbox.md) component in the same group, the setting of the **Checkbox** has a higher priority. 54 55Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md). 56Since API version 18, this attribute supports two-way binding through [!!](../../../quick-start/arkts-new-binding.md#two-way-binding-between-built-in-component-parameters). 57 58**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 59 60**Atomic service API**: This API can be used in atomic services since API version 11. 61 62**System capability**: SystemCapability.ArkUI.ArkUI.Full 63 64**Parameters** 65 66| Name| Type | Mandatory| Description | 67| ------ | ------- | ---- | ------------------------------------------------------------ | 68| value | boolean | Yes | Whether to select all.<br>Default value: **false**<br>**true**: Select all check boxes in the group. **false**: Do not select any check box in the group.| 69 70### selectAll<sup>18+</sup> 71 72selectAll(isAllSelected: Optional\<boolean>) 73 74Sets whether to select all. If the **select** attribute is set for a [Checkbox](ts-basic-components-checkbox.md) component in the same group, the setting of the **Checkbox** has a higher priority. Compared to [selectAll](#selectall), this API supports the **undefined** type for the **isAllSelected** parameter. 75 76This attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md) or [!!](../../../quick-start/arkts-new-binding.md). 77 78**Widget capability**: This API can be used in ArkTS widgets since API version 18. 79 80**Atomic service API**: This API can be used in atomic services since API version 18. 81 82**System capability**: SystemCapability.ArkUI.ArkUI.Full 83 84**Parameters** 85 86| Name | Type | Mandatory| Description | 87| ------------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 88| isAllSelected | [Optional](ts-universal-attributes-custom-property.md#optional12)\<boolean> | Yes | Whether to select all.<br>If **isAllSelected** is set to **undefined**, the default value **false** is used.<br>**true**: Select all check boxes in the group. **false**: Do not select any check box in the group.| 89 90### selectedColor 91 92selectedColor(value: ResourceColor) 93 94Sets the color of the selected check box. 95 96**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 97 98**Atomic service API**: This API can be used in atomic services since API version 11. 99 100**System capability**: SystemCapability.ArkUI.ArkUI.Full 101 102**Parameters** 103 104| Name| Type | Mandatory| Description | 105| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 106| value | [ResourceColor](ts-types.md#resourcecolor) | Yes | Color of the selected check box.<br>Default value: **$r('sys.color.ohos_id_color_text_primary_activated')**<br>An invalid value is handled as the default value.| 107 108### selectedColor<sup>18+</sup> 109 110selectedColor(resColor: Optional\<ResourceColor>) 111 112Sets the color of the selected check box. Compared to [selectedColor](#selectedcolor), this API supports the **undefined** type for the **resColor** parameter. 113 114**Widget capability**: This API can be used in ArkTS widgets since API version 18. 115 116**Atomic service API**: This API can be used in atomic services since API version 18. 117 118**System capability**: SystemCapability.ArkUI.ArkUI.Full 119 120**Parameters** 121 122| Name | Type | Mandatory| Description | 123| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 124| resColor | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[ResourceColor](ts-types.md#resourcecolor)> | Yes | Color of the selected check box.<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.| 125 126### unselectedColor<sup>10+</sup> 127 128unselectedColor(value: ResourceColor) 129 130Sets the border color of the check box when it is not selected. 131 132**Atomic service API**: This API can be used in atomic services since API version 11. 133 134**System capability**: SystemCapability.ArkUI.ArkUI.Full 135 136**Parameters** 137 138| Name| Type | Mandatory| Description | 139| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ | 140| 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')**| 141 142### unselectedColor<sup>18+</sup> 143 144unselectedColor(resColor: Optional\<ResourceColor>) 145 146Sets 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. 147 148**Atomic service API**: This API can be used in atomic services since API version 18. 149 150**System capability**: SystemCapability.ArkUI.ArkUI.Full 151 152**Parameters** 153 154| Name | Type | Mandatory| Description | 155| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 156| 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.| 157 158### mark<sup>10+</sup> 159 160mark(value: MarkStyle) 161 162Sets the check mark style of the check box. 163 164**Atomic service API**: This API can be used in atomic services since API version 11. 165 166**System capability**: SystemCapability.ArkUI.ArkUI.Full 167 168**Parameters** 169 170| Name| Type | Mandatory| Description | 171| ------ | -------------------------------------------- | ---- | -------------------- | 172| value | [MarkStyle](ts-types.md#markstyle10) | Yes | Check mark style of the check box.| 173 174### mark<sup>18+</sup> 175 176mark(style: Optional\<MarkStyle>) 177 178Sets 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. 179 180**Atomic service API**: This API can be used in atomic services since API version 18. 181 182**System capability**: SystemCapability.ArkUI.ArkUI.Full 183 184**Parameters** 185 186| Name| Type | Mandatory| Description | 187| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 188| style | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[MarkStyle](ts-types.md#markstyle10)> | Yes | Check mark style of the check box.<br>If **style** is set to **undefined**, the previous value is retained.| 189 190### checkboxShape<sup>12+</sup> 191 192checkboxShape(value: CheckBoxShape) 193 194Sets the check box shape of the check box group. 195 196**Widget capability**: This API can be used in ArkTS widgets since API version 12. 197 198**Atomic service API**: This API can be used in atomic services since API version 12. 199 200**System capability**: SystemCapability.ArkUI.ArkUI.Full 201 202**Parameters** 203 204| Name| Type | Mandatory| Description | 205| ------ | ----------------------------------------------------- | ---- | ------------------------------------------------------------ | 206| value | [CheckBoxShape](ts-appendix-enums.md#checkboxshape11) | Yes | Check box shape of the check box group.<br>Default value: **CheckBoxShape.CIRCLE**<br>**NOTE**<br>The shape of the check box group component follows the settings configured.<br>All check boxes within the check box group that do not have an individual shape set will conform to the shape of the check box group.<br>If a check box within the check box group has an individual shape set, that shape takes precedence over the check box group's shape.| 207 208### checkboxShape<sup>18+</sup> 209 210checkboxShape(shape: Optional\<CheckBoxShape>) 211 212Sets the check box shape of the check box group. Compared to [checkboxShape](#checkboxshape12)<sup>12+</sup>, this API supports the **undefined** type for the **shape** parameter. 213 214**Widget capability**: This API can be used in ArkTS widgets since API version 18. 215 216**Atomic service API**: This API can be used in atomic services since API version 18. 217 218**System capability**: SystemCapability.ArkUI.ArkUI.Full 219 220**Parameters** 221 222| Name| Type | Mandatory| Description | 223| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 224| shape | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[CheckBoxShape](ts-appendix-enums.md#checkboxshape11)> | Yes | Check box shape of the check box group.<br>If **shape** is set to **undefined**, the default value **CheckBoxShape.CIRCLE** is used.<br>**NOTE**<br>The shape of the check box group component follows the settings configured.<br>All check boxes within the check box group that do not have an individual shape set will conform to the shape of the check box group.<br>If a check box within the check box group has an individual shape set, that shape takes precedence over the check box group's shape.| 225 226## Events 227 228In addition to the [universal events](ts-component-general-events.md), the following events are supported. 229 230### onChange 231 232onChange(callback: OnCheckboxGroupChangeCallback) 233 234Triggered when the selected status of the check box group or any check box wherein changes. 235 236**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 237 238**Atomic service API**: This API can be used in atomic services since API version 11. 239 240**System capability**: SystemCapability.ArkUI.ArkUI.Full 241 242**Parameters** 243 244| Name | Type | Mandatory| Description | 245| -------- | ------------------------------------------------------------ | ---- | ------------------ | 246| callback | [OnCheckboxGroupChangeCallback](#oncheckboxgroupchangecallback18) | Yes | Information about the check box group.| 247 248### onChange<sup>18+</sup> 249 250onChange(callback: Optional\<OnCheckboxGroupChangeCallback>) 251 252Triggered when the selected status of the check box group or any check box wherein changes. Compared to [onChange](#onchange), this API supports the **undefined** type for the **callback** parameter. 253 254**Widget capability**: This API can be used in ArkTS widgets since API version 18. 255 256**Atomic service API**: This API can be used in atomic services since API version 18. 257 258**System capability**: SystemCapability.ArkUI.ArkUI.Full 259 260**Parameters** 261 262| Name | Type | Mandatory| Description | 263| -------- | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ | 264| callback | [Optional](ts-universal-attributes-custom-property.md#optional12)\<[OnCheckboxGroupChangeCallback](#oncheckboxgroupchangecallback18)> | Yes | Information about the check box group.<br>If **callback** is set to **undefined**, the callback function is not used.| 265 266## OnCheckboxGroupChangeCallback<sup>18+</sup> 267 268type OnCheckboxGroupChangeCallback = (value: CheckboxGroupResult) => void 269 270Information about the check box group. 271 272**Widget capability**: This API can be used in ArkTS widgets since API version 18. 273 274**Atomic service API**: This API can be used in atomic services since API version 18. 275 276**System capability**: SystemCapability.ArkUI.ArkUI.Full 277 278**Parameters** 279 280| Name| Type | Mandatory| Description | 281| ------ | --------------------------------------------------- | ---- | ------------------ | 282| value | [CheckboxGroupResult](#checkboxgroupresult)| Yes | Information about the check box group.| 283 284## CheckboxGroupResult 285 286**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 287 288**Atomic service API**: This API can be used in atomic services since API version 11. 289 290**System capability**: SystemCapability.ArkUI.ArkUI.Full 291 292| Name | Type | Read Only| Optional| Description | 293| ------ | ------ | ------- | ------- | ------- | 294| name | Array<string> | No| No| Names of all the selected check boxes in the group.| 295| status | [SelectStatus](#selectstatus) | No| No| Selected status.| 296 297## SelectStatus 298 299**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets. 300 301**Atomic service API**: This API can be used in atomic services since API version 11. 302 303**System capability**: SystemCapability.ArkUI.ArkUI.Full 304 305| Name | Description| 306| ----- | -------------------- | 307| All | All check boxes in the group are selected.| 308| Part | Some check boxes in the group are selected.| 309| None | None of the check boxes in the group are selected.| 310 311## Example 312 313### Example 1: Setting a Check Box Group 314 315This example demonstrates how to control the state of a group of check boxes to achieve a "select all" or "deselect all" effect. 316 317```ts 318// xxx.ets 319@Entry 320@Component 321struct CheckboxExample { 322 build() { 323 Scroll() { 324 Column() { 325 // Select All button 326 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 327 CheckboxGroup({ group: 'checkboxGroup' }) 328 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 329 .selectedColor('#007DFF') 330 .onChange((itemName: CheckboxGroupResult) => { 331 console.info("checkbox group content" + JSON.stringify(itemName)) 332 }) 333 Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 334 } 335 336 // Option 1 337 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 338 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 339 .selectedColor('#007DFF') 340 .shape(CheckBoxShape.ROUNDED_SQUARE) 341 .onChange((value: boolean) => { 342 console.info('Checkbox1 change is' + value) 343 }) 344 Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 345 }.margin({ left: 36 }) 346 347 // Option 2 348 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 349 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 350 .selectedColor('#007DFF') 351 .shape(CheckBoxShape.ROUNDED_SQUARE) 352 .onChange((value: boolean) => { 353 console.info('Checkbox2 change is' + value) 354 }) 355 Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 356 }.margin({ left: 36 }) 357 358 // Option 3 359 Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) { 360 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 361 .selectedColor('#007DFF') 362 .shape(CheckBoxShape.ROUNDED_SQUARE) 363 .onChange((value: boolean) => { 364 console.info('Checkbox3 change is' + value) 365 }) 366 Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500) 367 }.margin({ left: 36 }) 368 } 369 } 370 } 371} 372``` 373 374 375### Example 2: Customizing Check Mark Style 376 377This example shows how to customize the check mark style for a check box group by configuring the **mark** attribute. 378 379```ts 380// xxx.ets 381@Entry 382@Component 383struct Index { 384 385 build() { 386 Row() { 387 Column() { 388 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 389 CheckboxGroup({ group: 'checkboxGroup' }) 390 .checkboxShape(CheckBoxShape.ROUNDED_SQUARE) 391 .selectedColor(Color.Orange) 392 .onChange((itemName: CheckboxGroupResult) => { 393 console.info("checkbox group content" + JSON.stringify(itemName)) 394 }) 395 .mark({ 396 strokeColor:Color.Black, 397 size: 40, 398 strokeWidth: 5 399 }) 400 .unselectedColor(Color.Red) 401 .width(30) 402 .height(30) 403 Text('Select All').fontSize(20) 404 }.margin({right:15}) 405 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 406 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 407 .selectedColor(0x39a2db) 408 .shape(CheckBoxShape.ROUNDED_SQUARE) 409 .onChange((value: boolean) => { 410 console.info('Checkbox1 change is'+ value) 411 }) 412 .mark({ 413 strokeColor:Color.Black, 414 size: 50, 415 strokeWidth: 5 416 }) 417 .unselectedColor(Color.Red) 418 .width(30) 419 .height(30) 420 Text('Checkbox1').fontSize(20) 421 } 422 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 423 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 424 .selectedColor(0x39a2db) 425 .shape(CheckBoxShape.ROUNDED_SQUARE) 426 .onChange((value: boolean) => { 427 console.info('Checkbox2 change is' + value) 428 }) 429 .width(30) 430 .height(30) 431 Text('Checkbox2').fontSize(20) 432 } 433 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 434 Checkbox({ name: 'checkbox3', group: 'checkboxGroup' }) 435 .selectedColor(0x39a2db) 436 .shape(CheckBoxShape.ROUNDED_SQUARE) 437 .onChange((value: boolean) => { 438 console.info('Checkbox3 change is' + value) 439 }) 440 .width(30) 441 .height(30) 442 Text('Checkbox3').fontSize(20) 443 } 444 } 445 .width('100%') 446 } 447 .height('100%') 448 } 449} 450``` 451 452 453
