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-universal-attributes-size.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). 54 55**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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 the check box is selected.<br>Default value: **false**| 66 67### selectedColor 68 69selectedColor(value: ResourceColor) 70 71Sets the color of the check box when it is selected. 72 73**Widget capability**: This API can be used in ArkTS widgets since API version 9. 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 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.| 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**Atomic service API**: This API can be used in atomic services since API version 11. 92 93**System capability**: SystemCapability.ArkUI.ArkUI.Full 94 95**Parameters** 96 97| Name| Type | Mandatory| Description | 98| ------ | ------------------------------------------ | ---- | -------------------------- | 99| 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')**| 100 101### mark<sup>10+</sup> 102 103mark(value: MarkStyle) 104 105Sets the mark style of the check box. 106 107**Atomic service API**: This API can be used in atomic services since API version 11. 108 109**System capability**: SystemCapability.ArkUI.ArkUI.Full 110 111**Parameters** 112 113| Name| Type | Mandatory| Description | 114| ------ | -------------------------------------------- | ---- | ------------------------------------------------------------ | 115| 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.<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>} | 116 117### shape<sup>11+</sup> 118 119shape(value: CheckBoxShape) 120 121Sets the shape of the check box. 122 123**Widget capability**: This API can be used in ArkTS widgets since API version 11. 124 125**Atomic service API**: This API can be used in atomic services since API version 12. 126 127**System capability**: SystemCapability.ArkUI.ArkUI.Full 128 129**Parameters** 130 131| Name| Type | Mandatory| Description | 132| ------ | --------------------------------------------- | ---- | ------------------------------------------------------------ | 133| value | [CheckBoxShape](#checkboxshape11)| Yes | Shape of the check box.<br>Default value: **CheckBoxShape.CIRCLE**| 134 135### contentModifier<sup>12+</sup> 136 137contentModifier(modifier: ContentModifier\<CheckBoxConfiguration>) 138 139Creates a content modifier. 140 141**Atomic service API**: This API can be used in atomic services since API version 12. 142 143**System capability**: SystemCapability.ArkUI.ArkUI.Full 144 145**Parameters** 146 147| Name| Type | Mandatory| Description | 148| ------ | --------------------------------------------- | ---- | ------------------------------------------------ | 149| 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.| 150 151## Events 152 153In addition to the [universal events](ts-universal-events-click.md), the following attributes are supported. 154 155### onChange 156 157onChange(callback: OnCheckboxChangeCallback) 158 159Invoked when the selected state of the check box changes. 160 161**Widget capability**: This API can be used in ArkTS widgets since API version 9. 162 163**Atomic service API**: This API can be used in atomic services since API version 11. 164 165**System capability**: SystemCapability.ArkUI.ArkUI.Full 166 167**Parameters** 168 169| Name | Type | Mandatory| Description | 170| -------- | ------------------------------------------------------- | ---- | ---------------- | 171| callback | [OnCheckboxChangeCallback](#oncheckboxchangecallback13) | Yes | Callback used to return the selected state.| 172 173## OnCheckboxChangeCallback<sup>13+</sup> 174 175type OnCheckboxChangeCallback = (value: boolean) => void 176 177Represents the callback invoked when the selected state of the check box changes. 178 179**Widget capability**: This API can be used in ArkTS widgets since API version 13. 180 181**Atomic service API**: This API can be used in atomic services since API version 13. 182 183**System capability**: SystemCapability.ArkUI.ArkUI.Full 184 185**Parameters** 186 187| Name| Type | Mandatory| Description | 188| ------ | ------- | ---- | ------------------------------------------------- | 189| value | boolean | Yes | Whether the check box is selected. The value **true** means that the check box is selected, and **false** means the opposite.| 190 191## CheckBoxShape<sup>11+</sup> 192 193**Atomic service API**: This API can be used in atomic services since API version 12. 194 195**System capability**: SystemCapability.ArkUI.ArkUI.Full 196 197| Name | Value | Description | 198| -------------- | ---- | -------- | 199| CIRCLE | 0 | Circle. | 200| ROUNDED_SQUARE | 1 | Rounded square.| 201 202## CheckBoxConfiguration<sup>12+</sup> 203 204You need a custom class to implement the **ContentModifier** API. 205 206**Atomic service API**: This API can be used in atomic services since API version 12. 207 208**System capability**: SystemCapability.ArkUI.ArkUI.Full 209 210| Name| Type | Read Only | Optional | Description | 211| ------ | ------ | ------ |-------------------------------- |-------------------------------- | 212| name | string | No| No|Name of the check box.| 213| 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.| 214| triggerChange |Callback\<boolean>| No| No|Changes the selected state of the check box.| 215 216## Example 217 218### Example 1 219 220```ts 221// xxx.ets 222@Entry 223@Component 224struct CheckboxExample { 225 build() { 226 Flex({ justifyContent: FlexAlign.SpaceAround }) { 227 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 228 .select(true) 229 .selectedColor(0xed6f21) 230 .shape(CheckBoxShape.CIRCLE) 231 .onChange((value: boolean) => { 232 console.info('Checkbox1 change is' + value) 233 }) 234 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 235 .select(false) 236 .selectedColor(0x39a2db) 237 .shape(CheckBoxShape.ROUNDED_SQUARE) 238 .onChange((value: boolean) => { 239 console.info('Checkbox2 change is' + value) 240 }) 241 } 242 } 243} 244``` 245 246 247 248 249### Example 2 250 251```ts 252// xxx.ets 253@Entry 254@Component 255struct Index { 256 257 build() { 258 Row() { 259 Column() { 260 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 261 Checkbox({ name: 'checkbox1', group: 'checkboxGroup' }) 262 .selectedColor(0x39a2db) 263 .shape(CheckBoxShape.ROUNDED_SQUARE) 264 .onChange((value: boolean) => { 265 console.info('Checkbox1 change is'+ value) 266 }) 267 .mark({ 268 strokeColor:Color.Black, 269 size: 50, 270 strokeWidth: 5 271 }) 272 .unselectedColor(Color.Red) 273 .width(30) 274 .height(30) 275 Text('Checkbox1').fontSize(20) 276 } 277 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 278 Checkbox({ name: 'checkbox2', group: 'checkboxGroup' }) 279 .selectedColor(0x39a2db) 280 .shape(CheckBoxShape.ROUNDED_SQUARE) 281 .onChange((value: boolean) => { 282 console.info('Checkbox2 change is' + value) 283 }) 284 .width(30) 285 .height(30) 286 Text('Checkbox2').fontSize(20) 287 } 288 } 289 .width('100%') 290 } 291 .height('100%') 292 } 293} 294``` 295 296 297 298 299### Example 3 300This 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." 301 302```ts 303// xxx.ets 304class MyCheckboxStyle implements ContentModifier<CheckBoxConfiguration> { 305 selectedColor: Color = Color.White 306 constructor(selectedColor: Color) { 307 this.selectedColor = selectedColor; 308 } 309 applyContent() : WrappedBuilder<[CheckBoxConfiguration]> 310 { 311 return wrapBuilder(buildCheckbox) 312 } 313} 314 315@Builder function buildCheckbox(config: CheckBoxConfiguration) { 316 Column({space:10}) { 317 Text(config.name + (config.selected ? " (Selected)" : " (Unselected)")).margin({right : 70, top : 50}) 318 Text(config.enabled ? "enabled true" : "enabled false").margin({right : 110}) 319 Shape() { 320 Path().width(100).height(100).commands('M100 0 L0 100 L50 200 L150 200 L200 100 Z').fillOpacity(0).strokeWidth(3).onClick(()=>{ 321 if (config.selected) { 322 config.triggerChange(false) 323 } else { 324 config.triggerChange(true) 325 } 326 }).opacity(config.enabled ? 1 : 0.1) 327 Path().width(10).height(10).commands('M50 0 L100 100 L0 100 Z') 328 .visibility(config.selected ? Visibility.Visible : Visibility.Hidden) 329 .fill(config.selected ? (config.contentModifier as MyCheckboxStyle).selectedColor : Color.Black) 330 .stroke((config.contentModifier as MyCheckboxStyle).selectedColor) 331 .margin({left:10,top:10}) 332 .opacity(config.enabled ? 1 : 0.1) 333 } 334 .width(300) 335 .height(200) 336 .viewPort({ x: 0, y: 0, width: 310, height: 310 }) 337 .strokeLineJoin(LineJoinStyle.Miter) 338 .strokeMiterLimit(5) 339 .margin({left:50}) 340 } 341} 342 343@Entry 344@Component 345struct Index { 346 @State checkboxEnabled: boolean = true; 347 build() { 348 Column({ space: 100 }) { 349 Checkbox({ name: 'Check box status', group: 'checkboxGroup' }) 350 .contentModifier(new MyCheckboxStyle(Color.Red)) 351 .onChange((value: boolean) => { 352 console.info('Checkbox change is' + value) 353 }).enabled(this.checkboxEnabled) 354 355 Row() { 356 Toggle({ type: ToggleType.Switch, isOn: true }).onChange((value: boolean) => { 357 if (value) { 358 this.checkboxEnabled = true 359 } else { 360 this.checkboxEnabled = false 361 } 362 }) 363 }.position({ x: 50, y: 130 }) 364 }.margin({top : 30}) 365 } 366} 367``` 368 369 370 371 372### Example 4 373In this example, a **Text** component is used to indicate that the check box is selected. 374```ts 375// xxx.ets 376@Entry 377@Component 378struct CheckboxExample { 379 @Builder 380 indicatorBuilder(value: number) { 381 Column(){ 382 Text(value > 99 ? '99+': value.toString()) 383 .textAlign(TextAlign.Center) 384 .fontSize(value > 99 ? '16vp': '20vp') 385 .fontWeight(FontWeight.Medium) 386 .fontColor('#ffffffff') 387 } 388 } 389 build() { 390 Row() { 391 Column() { 392 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center}) { 393 Checkbox({ name: 'checkbox1', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(9)}}) 394 .shape(CheckBoxShape.CIRCLE) 395 .onChange((value: boolean) => { 396 console.info('Checkbox1 change is'+ value) 397 }) 398 .mark({ 399 strokeColor:Color.Black, 400 size: 50, 401 strokeWidth: 5 402 }) 403 .width(30) 404 .height(30) 405 Text('Checkbox1').fontSize(20) 406 }.padding(15) 407 Flex({ justifyContent: FlexAlign.Center, alignItems: ItemAlign.Center }) { 408 Checkbox({ name: 'checkbox2', group: 'checkboxGroup', indicatorBuilder:()=>{this.indicatorBuilder(100)}}) 409 .shape(CheckBoxShape.ROUNDED_SQUARE) 410 .onChange((value: boolean) => { 411 console.info('Checkbox2 change is' + value) 412 }) 413 .width(30) 414 .height(30) 415 Text('Checkbox2').fontSize(20) 416 } 417 } 418 .width('100%') 419 } 420 .height('100%') 421 } 422} 423``` 424 425 426 427
