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| Name | Type | Mandatory | Description |
40| -------- | -------- | -------- | -------- |
41| 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. |
42
43## Attributes
44
45In addition to the [universal attributes](ts-universal-attributes-size.md), the following attributes are supported.
46
47### selectAll
48
49selectAll(value: boolean)
50
51Sets 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.
52
53Since API version 10, this attribute supports two-way binding through [$$](../../../quick-start/arkts-two-way-sync.md).
54
55**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
56
57**Atomic service API**: This API can be used in atomic services since API version 11.
58
59**System capability**: SystemCapability.ArkUI.ArkUI.Full
60
61**Parameters**
62
63| Name | Type   | Mandatory | Description                        |
64| ------ | ------- | ---- | ---------------------------- |
65| value  | boolean | Yes  | Whether to select all.<br>Default value: **false** |
66
67### selectedColor
68
69selectedColor(value: ResourceColor)
70
71Sets the color of the selected check box.
72
73**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
74
75**Atomic service API**: This API can be used in atomic services since API version 11.
76
77**System capability**: SystemCapability.ArkUI.ArkUI.Full
78
79**Parameters**
80
81| Name | Type                                      | Mandatory | Description                                                        |
82| ------ | ------------------------------------------ | ---- | ------------------------------------------------------------ |
83| 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. |
84
85### unselectedColor<sup>10+</sup>
86
87unselectedColor(value: ResourceColor)
88
89Sets the border color of the check box when it is not selected.
90
91**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
92
93**Atomic service API**: This API can be used in atomic services since API version 11.
94
95**System capability**: SystemCapability.ArkUI.ArkUI.Full
96
97**Parameters**
98
99| Name | Type                                      | Mandatory | Description                |
100| ------ | ------------------------------------------ | ---- | -------------------- |
101| value  | [ResourceColor](ts-types.md#resourcecolor) | Yes  | Border color of the check box when it is not selected.<br>Default value: **'#33ffffff'** |
102
103### mark<sup>10+</sup>
104
105mark(value: MarkStyle)
106
107Sets the mark style of the check box.
108
109**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
110
111**Atomic service API**: This API can be used in atomic services since API version 11.
112
113**System capability**: SystemCapability.ArkUI.ArkUI.Full
114
115**Parameters**
116
117| Name | Type                             | Mandatory | Description                |
118| ------ | --------------------------------- | ---- | -------------------- |
119| value  | [MarkStyle](ts-types.md#markstyle10) | Yes  | Mark style of the check box. |
120
121### checkboxShape<sup>12</sup>
122
123checkboxShape(value: CheckBoxShape)
124
125Sets the shape of the check box group.
126
127**Widget capability**: This API can be used in ArkTS widgets since API version 12.
128
129**Atomic service API**: This API can be used in atomic services since API version 12.
130
131**System capability**: SystemCapability.ArkUI.ArkUI.Full
132
133**Parameters**
134
135| Name | Type                                               | Mandatory | Description              |
136| ------ | --------------------------------------------------- | ---- | ------------------ |
137| value  | [CheckBoxShape](ts-basic-components-checkbox.md#checkboxshape11) | Yes  | 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.
138
139## Events
140
141In addition to the [universal events](ts-universal-events-click.md), the following events are supported.
142
143### onChange
144
145onChange(callback: (event: CheckboxGroupResult) => void )
146
147Invoked when the selected status of the check box group or any check box wherein changes.
148
149**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
150
151**Atomic service API**: This API can be used in atomic services since API version 11.
152
153**System capability**: SystemCapability.ArkUI.ArkUI.Full
154
155**Parameters**
156
157| Name | Type                                               | Mandatory | Description              |
158| ------ | --------------------------------------------------- | ---- | ------------------ |
159| event  | [CheckboxGroupResult](#checkboxgroupresult) | Yes  | Information about the check box group. |
160
161## CheckboxGroupResult
162
163**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
164
165**Atomic service API**: This API can be used in atomic services since API version 11.
166
167| Name    | Type  | Description     |
168| ------ | ------ | ------- |
169| name   | Array&lt;string&gt; | Names of all the selected check boxes in the group. |
170| status | [SelectStatus](#selectstatus)  | Selected status. |
171
172## SelectStatus
173
174**Widget capability**: Since API version 9, this feature is supported in ArkTS widgets.
175
176**Atomic service API**: This API can be used in atomic services since API version 11.
177
178| Name | Description |
179| ----- | -------------------- |
180| All   | All check boxes in the group are selected. |
181| Part  | Some check boxes in the group are selected. |
182| None  | None of the check boxes in the group are selected. |
183
184## Example
185
186### Example 1
187
188```ts
189// xxx.ets
190@Entry
191@Component
192struct CheckboxExample {
193  build() {
194    Scroll() {
195      Column() {
196        // Select All button
197        Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
198          CheckboxGroup({ group: 'checkboxGroup' })
199            .checkboxShape(CheckBoxShape.ROUNDED_SQUARE)
200            .selectedColor('#007DFF')
201            .onChange((itemName: CheckboxGroupResult) => {
202              console.info("checkbox group content" + JSON.stringify(itemName))
203            })
204          Text('Select All').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
205        }
206
207        // Option 1
208        Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
209          Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
210            .selectedColor('#007DFF')
211            .shape(CheckBoxShape.ROUNDED_SQUARE)
212            .onChange((value: boolean) => {
213              console.info('Checkbox1 change is' + value)
214            })
215          Text('Checkbox1').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
216        }.margin({ left: 36 })
217
218        // Option 2
219        Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
220          Checkbox({ name: 'checkbox2', group: 'checkboxGroup' })
221            .selectedColor('#007DFF')
222            .shape(CheckBoxShape.ROUNDED_SQUARE)
223            .onChange((value: boolean) => {
224              console.info('Checkbox2 change is' + value)
225            })
226          Text('Checkbox2').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
227        }.margin({ left: 36 })
228
229        // Option 3
230        Flex({ justifyContent: FlexAlign.Start, alignItems: ItemAlign.Center }) {
231          Checkbox({ name: 'checkbox3', group: 'checkboxGroup' })
232            .selectedColor('#007DFF')
233            .shape(CheckBoxShape.ROUNDED_SQUARE)
234            .onChange((value: boolean) => {
235              console.info('Checkbox3 change is' + value)
236            })
237          Text('Checkbox3').fontSize(14).lineHeight(20).fontColor('#182431').fontWeight(500)
238        }.margin({ left: 36 })
239      }
240    }
241  }
242}
243```
244![checkboxGroup](figures/checkboxGroup.gif)
245
246### Example 2
247
248```ts
249// xxx.ets
250@Entry
251@Component
252struct Index {
253
254  build() {
255    Row() {
256      Column() {
257        Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
258          CheckboxGroup({ group: 'checkboxGroup' })
259            .checkboxShape(CheckBoxShape.ROUNDED_SQUARE)
260            .selectedColor(Color.Orange)
261            .onChange((itemName: CheckboxGroupResult) => {
262              console.info("checkbox group content" + JSON.stringify(itemName))
263            })
264            .mark({
265              strokeColor:Color.Black,
266              size: 40,
267              strokeWidth: 5
268            })
269            .unselectedColor(Color.Red)
270            .width(30)
271            .height(30)
272          Text('Select All').fontSize(20)
273        }.margin({right:15})
274        Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
275          Checkbox({ name: 'checkbox1', group: 'checkboxGroup' })
276            .selectedColor(0x39a2db)
277            .shape(CheckBoxShape.ROUNDED_SQUARE)
278            .onChange((value: boolean) => {
279              console.info('Checkbox1 change is'+ value)
280            })
281            .mark({
282              strokeColor:Color.Black,
283              size: 50,
284              strokeWidth: 5
285            })
286            .unselectedColor(Color.Red)
287            .width(30)
288            .height(30)
289          Text('Checkbox1').fontSize(20)
290        }
291        Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
292          Checkbox({ name: 'checkbox2', group: 'checkboxGroup' })
293            .selectedColor(0x39a2db)
294            .shape(CheckBoxShape.ROUNDED_SQUARE)
295            .onChange((value: boolean) => {
296              console.info('Checkbox2 change is' + value)
297            })
298            .width(30)
299            .height(30)
300          Text('Checkbox2').fontSize(20)
301        }
302        Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) {
303          Checkbox({ name: 'checkbox3', group: 'checkboxGroup' })
304            .selectedColor(0x39a2db)
305            .shape(CheckBoxShape.ROUNDED_SQUARE)
306            .onChange((value: boolean) => {
307              console.info('Checkbox3 change is' + value)
308            })
309            .width(30)
310            .height(30)
311          Text('Checkbox3').fontSize(20)
312        }
313      }
314      .width('100%')
315    }
316    .height('100%')
317  }
318}
319```
320
321![checkboxGroup](figures/checkboxGroup2.gif)
322