1# ChipGroup 2 3**ChipGroup** is an advanced component that provides a group of chips for scenarios such as categorizing files or resource content. 4 5> **NOTE** 6> 7> This component is supported since API version 12. Updates will be marked with a superscript to indicate their earliest API version. 8 9## Child Components 10 11Not supported 12 13## ChipGroup 14 15``` 16ChipGroup({ 17 items: ChipGroupItemOptions[], 18 itemStyle?: ChipItemStyle, 19 selectedIndexes?: Array<number>, 20 multiple?: boolean, 21 chipGroupSpace?: ChipGroupSpaceOptions, 22 chipGroupPadding?: ChipGroupPaddingOptions, 23 onChange?: (selectedIndexes: Array<number>) => void, 24 suffix?: Callback<void> 25}) 26``` 27 28**Decorator**: @Component 29 30**Atomic service API**: This API can be used in atomic services since API version 12. 31 32**System capability**: SystemCapability.ArkUI.ArkUI.Full 33 34**Parameters** 35 36| Name | Type | Mandatory| Description | 37| --------------- | ----------------------------------------------- | ---- | ------------------------------------------------------------ | 38| items | [ChipGroupItemOptions[]](#chipgroupitemoptions) | Yes | Specific attributes of individual chips. For details, see [ChipGroupItemOptions[]](#chipgroupitemoptions).<br>If this parameter is set to **undefined**, the chip group is empty by default. | 39| itemStyle | [ChipItemStyle](#chipitemstyle) | No | Chip style, including the color and size. For details, see [ChipItemStyle](#chipitemstyle).<br>If this parameter is set to **undefined**, the default chip style is used. | 40| selectedIndexes | Array<number> | No | Index of the selected chip.<br>If this parameter is set to **undefined**, the first chip is selected. | 41| multiple | boolean | No | Whether multiple chips can be selected.<br>**true**: Multiple chips can be selected.<br>**false**: Only one chip can be selected.<br>Default value: **false**<br>If this parameter is set to **undefined**, the default value is used. | 42| chipGroupSpace | [ChipGroupSpaceOptions](#chipgroupspaceoptions) | No | Left and right padding, and the spacing between chips. For details, see [ChipGroupSpaceOptions](#chipgroupspaceoptions).<br>If this parameter is set to **undefined**, the default value is used.| 43| chipGroupPadding | [ChipGroupPaddingOptions](#chipgrouppaddingoptions) | No | Top and bottom padding, used to control the overall height. For details, see [ChipGroupPaddingOptions](#chipgrouppaddingoptions).<br>If this parameter is set to **undefined**, the default value is used.| 44| onChange | (selectedIndexes: Array<number>) => void | No | Callback invoked when the chip status changes.<br>If the value is **undefined**, the event is unbound. | 45| suffix | ()=>void | No | Suffix, which is a builder customized by the user and requires importing the [IconGroupSuffix](#icongroupsuffix) API when used.<br>Default value: The suffix is not displayed if not passed.| 46 47> **NOTE** 48> 49> 1. When **multiple** is set to **false**, if **selectedIndexes** is not passed in, the first chip is automatically selected by default. However, if the provided **selectedIndexes** includes multiple elements, the chip at the first index is selected by default. 50> 51> 2. For the **suffix** API to work, you must include the **IconGroupSuffix** API when implementing it. If no value is specified for **suffix**, no suffix will be displayed. 52> 53> 3. The icon fill colors, such as **fillColor** and **activedFillColor**, are set to be consistent with the font color (**fontColor**). To differentiate the icon colors from the font color, include **prefixSymbol** when you pass in [ChipGroupSpaceOptions](#chipgroupspaceoptions). 54 55## ChipGroupItemOptions 56 57Defines the specific attributes of individual chips. 58 59**Atomic service API**: This API can be used in atomic services since API version 12. 60 61| Name | Type | Mandatory| Description | 62| ---------- | ----------------------------- | ---- | ----------------------------------- | 63| prefixIcon | [IconOptions](#iconoptions) | No | Prefix image icon of the chip. | 64| prefixSymbol | [ChipSymbolGlyphOptions](ohos-arkui-advanced-Chip.md#chipsymbolglyphoptions12) | No | Prefix symbol glyph icon of the chip. | 65| label | [LabelOptions](#labeloptions) | Yes | Text of the chip. | 66| suffixIcon | [IconOptions](#iconoptions) | No | Suffix image icon of the chip. | 67| suffixSymbol | [ChipSymbolGlyphOptions](ohos-arkui-advanced-Chip.md#chipsymbolglyphoptions12) | No | Suffix symbol glyph icon of the chip. | 68| allowClose | boolean | No | Whether to show the close icon.<br>Default value: **false** | 69 70>**NOTE** 71> 72>If **suffixIcon** is specified, **allowClose** has no effect. 73 74## ChipItemStyle 75 76Defines the common attributes shared by all chips in the chip group. 77 78**Atomic service API**: This API can be used in atomic services since API version 12. 79 80| Name | Type | Mandatory| Description | 81| ----------------------- | ---------------------- | ---- | ------------------------------- | 82| size | [ChipSize](ohos-arkui-advanced-Chip.md#chipsize) \| [SizeOptions](ts-types.md#sizeoptions) | No | Chip size. To use this API, you must import the **ChipSize** type from the **Chip** component.<br>Default value: **ChipSize**: **ChipSize.NORMAL**<br> If this parameter is set to **undefined**, the default value is used. | 83| backgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the chip.<br>Default value: **$r('sys.color.ohos_id_color_button_normal')**<br>If this parameter is set to **undefined**, the default value is used. | 84| fontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the chip.<br>Default value: **$r('sys.color.ohos_id_color_text_primary')**<br>If this parameter is set to **undefined**, the default value is used. | 85| selectedFontColor | [ResourceColor](ts-types.md#resourcecolor) | No | Font color of the chip when it is activated or selected.<br>Default value: **$r('sys.color.ohos_id_color_text_primary_contrary')**<br>If this parameter is set to **undefined**, the default value is used. | 86| selectedBackgroundColor | [ResourceColor](ts-types.md#resourcecolor) | No | Background color of the chip when it is activated or selected.<br>Default value: **$r('sys.color.ohos_id_color_emphasize')**<br>If this parameter is set to **undefined**, the default value is used. | 87 88> **NOTE** 89> 90> 1. The size settings for chips can be of two types: (1) **ChipSize**, which conveniently offers two size options, **NORMAL** and **SMALL**; (2) **SizeOptions**. 91> 92> 2. If **undefined** is assigned to **backgroundColor** or **selectedBackgroundColor**, the default background color is used. If an invalid value is assigned, the background color is transparent. 93 94## ChipGroupSpaceOptions 95 96Defines the left and right padding of the chip group, and the spacing between chips. 97 98**Atomic service API**: This API can be used in atomic services since API version 12. 99 100| Name | Type | Mandatory| Description | 101| ---------- | -------------- | ---- | ------------------------------------------------ | 102| itemSpace | string \| number | No | Spacing between chips. Percentage values are not supported.<br>Default value: **8**<br>Unit: vp<br>If this parameter is set to **undefined**, the default value is used. | 103| startSpace | [Length](ts-types.md#length) | No | Left padding. Percentage values are not supported.<br>Default value: **16**<br>Unit: vp<br>If this parameter is set to **undefined**, the default value is used. | 104| endSpace | [Length](ts-types.md#length) | No | Right padding. Percentage values are not supported.<br>Default value: **16**<br>Unit: vp<br>If this parameter is set to **undefined**, the default value is used.| 105 106## ChipGroupPaddingOptions 107 108Defines the top and bottom padding of the chip group, used to control the overall height. 109 110**Atomic service API**: This API can be used in atomic services since API version 12. 111 112| Name | Type | Mandatory| Description | 113| ------ | -------------- | ---- | ------------------------------------------------ | 114| top | [Length](ts-types.md#length) | Yes | Top padding. Percentage values are not supported.<br>Default value: **14**<br>If this parameter is set to **undefined**, the default value is used. | 115| bottom | [Length](ts-types.md#length) | Yes | Bottom padding. Percentage values are not supported.<br>Default value: **14**<br>If this parameter is set to **undefined**, the default value is used. | 116 117## IconGroupSuffix 118 119**Decorator**: @Component 120 121**Atomic service API**: This API can be used in atomic services since API version 12. 122 123**System capability**: SystemCapability.ArkUI.ArkUI.Full 124 125**Parameters** 126 127| Name | Type | Mandatory| Description | 128| -------- | ---------------------- | ---- | ----------------------------------------------| 129| items | Array<[IconItemOptions](#iconitemoptions) \| [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md)> | Yes | Custom builder items.| 130 131> **NOTE** 132> 133> With **SymbolGlyphModifier**, neither modifying the animation type with **symbolEffect** nor setting the effect strategy with **effectStrategy** is supported. 134> 135 136## IconItemOptions 137 138Defines the tail builder, which imposes limitations on the settings for the background size and color. 139 140**Atomic service API**: This API can be used in atomic services since API version 12. 141 142| Name | Type | Mandatory| Description | 143| -------- | -------------- | ---- | ------------------------------ | 144| icon | [IconOptions](#iconoptions) | Yes | Custom builder icon. | 145| action | Callback\<void> | Yes | Callback of custom builder items.<br>If the value is **undefined**, the event is unbound. | 146 147## IconOptions 148 149Defines the common attributes of icons. 150 151**Atomic service API**: This API can be used in atomic services since API version 12. 152 153| Name| Type | Mandatory| Description | 154| ---- | -------------------------------------- | ---- | ------------------------------------------------------------ | 155| src | [ResourceStr](ts-types.md#resourcestr) | Yes | Icon source, which can be a specific image path or an image reference. | 156| size | [SizeOptions](ts-types.md#sizeoptions) | No | Icon size. Percentage values are not supported.<br>When the chip size is **ChipSize.SMALL**, the default suffix is at {width: 16, height: 16}.<br>When the chip size is **ChipSize.NORMAL**, the default suffix is at {width: 24, height: 24}.<br> To dynamically change the size, you must use the [SymbolGlyphModifier](ts-universal-attributes-attribute-modifier.md) type when importing the [IconGroupSuffix](#icongroupsuffix) API.| 157 158## LabelOptions 159 160Defines the common attributes of labels. 161 162**Atomic service API**: This API can be used in atomic services since API version 12. 163 164| Name| Type | Mandatory | Description | 165| ---- | ------ | ---- | -------- | 166| text | string | Yes | Text of the chip. | 167 168## Example 169 170### Example 1: Suffix Not Included 171 172```typescript 173import { ChipSize, ChipGroup } from '@kit.ArkUI' 174 175@Entry 176@Preview 177@Component 178struct Index { 179 @State selected_index: Array<number> = [0, 1, 2, 3, 4, 5, 6] 180 build() { 181 Column() { 182 ChipGroup({ 183 items: [ 184 { 185 prefixIcon: { src: $r('app.media.icon') }, 186 label: { text: "Chip 1" }, 187 suffixIcon: { src: $r('sys.media.ohos_ic_public_cut') }, 188 allowClose: false 189 }, 190 { 191 prefixIcon: { src: $r('sys.media.ohos_ic_public_copy') }, 192 label: { text: "Chip 2" }, 193 allowClose: true 194 }, 195 { 196 prefixIcon: { src: $r('sys.media.ohos_ic_public_clock') }, 197 label: { text: "Chip 3" }, 198 allowClose: true 199 }, 200 { 201 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') }, 202 label: { text: "Chip 4" }, 203 allowClose: true 204 }, 205 { 206 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_mirror') }, 207 label: { text: "Chip 5" }, 208 allowClose: true 209 }, 210 { 211 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') }, 212 label: { text: "Chip 6" }, 213 allowClose: true 214 }, 215 ], 216 itemStyle: { 217 size: ChipSize.SMALL, 218 backgroundColor: $r('sys.color.ohos_id_color_button_normal'), 219 fontColor: $r('sys.color.ohos_id_color_text_primary'), 220 selectedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'), 221 selectedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'), 222 }, 223 selectedIndexes: this.selected_index, 224 multiple: false, 225 chipGroupSpace: { itemSpace: 8, endSpace: 0 }, 226 chipGroupPadding: { top: 10, bottom: 10 }, 227 onChange: (activatedChipsIndex:Array<number>) => { 228 console.log('chips on clicked, activated index ' + activatedChipsIndex) 229 }, 230 }) 231 } 232 } 233} 234``` 235 236 237 238### Example 2: Suffix Included 239 240```typescript 241import { ChipSize, ChipGroup, IconGroupSuffix } from '@kit.ArkUI' 242 243@Entry 244@Preview 245@Component 246struct Index { 247 @State selected_index: Array<number> = [0, 1, 2, 3, 4, 5, 6] 248 @State selected_state: boolean = true; 249 250 @LocalBuilder 251 ChipGroupSuffix(): void { 252 IconGroupSuffix({ 253 items: [{ 254 icon: { src: $r('sys.media.ohos_ic_public_search_filled'), size: { width: 36, height: 36 } }, 255 action: () => { 256 if (this.selected_state == false) { 257 this.selected_index = [0, 1, 2, 3, 4, 5, 6] 258 this.selected_state = true 259 } else { 260 this.selected_index = [] 261 this.selected_state = false 262 } 263 } 264 } 265 ] 266 }) 267 } 268 269 build() { 270 Column() { 271 ChipGroup({ 272 items: [ 273 { 274 prefixIcon: { src: $r('app.media.icon') }, 275 label: { text: "Chip 1" }, 276 suffixIcon: { src: $r('sys.media.ohos_ic_public_cut') }, 277 allowClose: false 278 }, 279 { 280 prefixIcon: { src: $r('sys.media.ohos_ic_public_copy') }, 281 label: { text: "Chip 2" }, 282 allowClose: true 283 }, 284 { 285 prefixIcon: { src: $r('sys.media.ohos_ic_public_clock') }, 286 label: { text: "Chip 3" }, 287 allowClose: true 288 }, 289 { 290 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') }, 291 label: { text: "Chip 4" }, 292 allowClose: true 293 }, 294 { 295 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_mirror') }, 296 label: { text: "Chip 5" }, 297 allowClose: true 298 }, 299 { 300 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') }, 301 label: { text: "Chip 6" }, 302 allowClose: true 303 }, 304 ], 305 itemStyle: { 306 size: ChipSize.NORMAL, 307 backgroundColor: $r('sys.color.ohos_id_color_button_normal'), 308 fontColor: $r('sys.color.ohos_id_color_text_primary'), 309 selectedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'), 310 selectedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'), 311 }, 312 selectedIndexes: this.selected_index, 313 multiple: true, 314 chipGroupSpace: { itemSpace: 8, endSpace: 0 }, 315 chipGroupPadding: { top: 10, bottom: 10 }, 316 onChange: (activatedChipsIndex: Array<number>) => { 317 console.log('chips on clicked, activated index ' + activatedChipsIndex) 318 }, 319 suffix: this.ChipGroupSuffix 320 }) 321 } 322 } 323} 324``` 325 326 327 328### Example 3 329This example implements **IconGroupSuffix** and **ChipGroup** with **SymbolGlyph** resources. 330```typescript 331import { ChipSize, ChipGroup, IconGroupSuffix, SymbolGlyphModifier } from '@kit.ArkUI' 332 333@Entry 334@Preview 335@Component 336struct Index { 337 @State selected_index: Array<number> = [0, 1, 2, 3, 4, 5, 6]; 338 @State selected_state: boolean = true; 339 @State prefixModifierNormal: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_star')); 340 @State prefixModifierActivated: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_star')).fontColor([Color.Red]); 341 @State suffixModifierNormal: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_wifi')); 342 @State suffixModifierActivated: SymbolGlyphModifier = new SymbolGlyphModifier($r('sys.symbol.ohos_wifi')).fontColor([Color.Red]); 343 344 @LocalBuilder 345 ChipGroupSuffix(): void { 346 IconGroupSuffix({ 347 items: [ 348 new SymbolGlyphModifier($r('sys.symbol.magnifyingglass')) 349 .onClick(() => { 350 if (this.selected_state == false) { 351 this.selected_index = [0, 1, 2, 3, 4, 5, 6]; 352 this.selected_state = true; 353 } else { 354 this.selected_index = []; 355 this.selected_state = false; 356 } 357 }) 358 ] 359 }) 360 } 361 362 build() { 363 Column() { 364 ChipGroup({ 365 items: [ 366 { 367 prefixSymbol: { normal: this.prefixModifierNormal, activated: this.prefixModifierActivated }, 368 label: { text: "Chip 1" }, 369 suffixSymbol: { normal: this.suffixModifierNormal, activated: this.suffixModifierActivated }, 370 allowClose: false, 371 }, 372 { 373 prefixSymbol: { normal: this.prefixModifierNormal, activated: this.prefixModifierActivated }, 374 label: { text: "Chip 2" }, 375 allowClose: true, 376 }, 377 { 378 prefixIcon: { src: $r('sys.media.ohos_ic_public_clock') }, 379 label: { text: "Chip 3" }, 380 allowClose: true, 381 }, 382 { 383 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') }, 384 label: { text: "Chip 4" }, 385 allowClose: true, 386 }, 387 { 388 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_mirror') }, 389 label: { text: "Chip 5" }, 390 allowClose: true, 391 }, 392 { 393 prefixIcon: { src: $r('sys.media.ohos_ic_public_cast_stream') }, 394 label: { text: "Chip 6" }, 395 allowClose: true, 396 }, 397 ], 398 itemStyle: { 399 size: ChipSize.NORMAL, 400 backgroundColor: $r('sys.color.ohos_id_color_button_normal'), 401 fontColor: $r('sys.color.ohos_id_color_text_primary'), 402 selectedBackgroundColor: $r('sys.color.ohos_id_color_emphasize'), 403 selectedFontColor: $r('sys.color.ohos_id_color_text_primary_contrary'), 404 }, 405 selectedIndexes: this.selected_index, 406 multiple: true, 407 chipGroupSpace: { itemSpace: 8, endSpace: 0 }, 408 chipGroupPadding: { top: 10, bottom: 10 }, 409 onChange: (activatedChipsIndex: Array<number>) => { 410 console.log('chips on clicked, activated index ' + activatedChipsIndex) 411 }, 412 suffix: this.ChipGroupSuffix 413 }) 414 } 415 } 416} 417 418``` 419 420
