1# ListItemGroup
2
3The **ListItemGroup** component is used to display list item groups. It must be used with the [List](ts-container-list.md) component. Unless specified otherwise, it spans the entire width of the **List** component.
4
5> **NOTE**
6>
7> - This component is supported since API version 9. Updates will be marked with a superscript to indicate their earliest API version.
8> - This component can be used only as a child of [List](ts-container-list.md).
9> - The **ListItemGroup** component does not support the universal attribute [aspectRatio](ts-universal-attributes-layout-constraints.md).
10> - If the parent **List** component of **ListItemGroup** has its **listDirection** attribute set to **Axis.Vertical**, setting the [universal attribute height](ts-universal-attributes-size.md) has no effect. In this case, the height of the **ListItemGroup** component is fixed at the sum of the component's header height, footer height, and total height of the list items.
11> - If the parent **List** component of **ListItemGroup** has its **listDirection** attribute set to **Axis.Horizontal**, setting the [universal attribute width](ts-universal-attributes-size.md) has no effect. In this case, the width of the **ListItemGroup** component is fixed at the sum of the component's header width, footer width, and total width of the list items.
12> - The list items in the **ListItemGroup** component cannot be edited or dragged. This means that their **editable** attribute does not take effect.
13> - The **ListItemGroup** ignores the **direction** attribute for setting the layout direction; instead, it adopts the layout direction of its parent **List** component.
14
15## Child Components
16
17This component supports the [ListItem](ts-container-listitem.md) child component.
18
19
20## APIs
21
22ListItemGroup(options?: ListItemGroupOptions)
23
24**Atomic service API**: This API can be used in atomic services since API version 11.
25
26**System capability**: SystemCapability.ArkUI.ArkUI.Full
27
28**Parameters**
29
30| Name| Type| Mandatory| Description|
31| -------- | -------- | -------- | -------- |
32| options |  [ListItemGroupOptions](#listitemgroupoptions)| No| Parameters of the list item group.|
33
34## ListItemGroupOptions
35
36**System capability**: SystemCapability.ArkUI.ArkUI.Full
37
38| Name             | Type                                           | Mandatory| Description                                                    |
39| ------------------- | --------------------------------------------------- | ---- | ------------------------------------------------------------ |
40| header              | [CustomBuilder](ts-types.md#custombuilder8)     | No  | Header of the list item group.<br>**NOTE**<br>One child component, or no child component at all, can be placed inside.<br>**Atomic service API**: This API can be used in atomic services since API version 11.              |
41| headerComponent<sup>13+</sup>              | [ComponentContent](../js-apis-arkui-ComponentContent.md)       | No  | Header of the list item group, in the type of ComponentContent.<br>**NOTE**<br>One child component, or no child component at all, can be placed inside. This parameter takes precedence over the **header** parameter. This means that, if both **header** and **headerComponent** are set, the value of **headerComponent** is used.<br>To avoid display issues, do not assign the same **headerComponent** to different **ListItemGroup** components.<br>**Atomic service API**: This API can be used in atomic services since API version 13.             |
42| footer              | [CustomBuilder](ts-types.md#custombuilder8)       | No  | Footer of the list item group.<br>**NOTE**<br>One child component, or no child component at all, can be placed inside.<br>**Atomic service API**: This API can be used in atomic services since API version 11.              |
43| footerComponent<sup>13+</sup>              | [ComponentContent](../js-apis-arkui-ComponentContent.md)       | No  | Footer of the list item group, in the type of ComponentContent.<br>**NOTE**<br>One child component, or no child component at all, can be placed inside. This parameter takes precedence over the **footer** parameter. This means that, if both **footer** and **footerComponent** are set, the value of **footerComponent** is used.<br>To avoid display issues, do not assign the same **footerComponent** to different **ListItemGroup** components.<br>**Atomic service API**: This API can be used in atomic services since API version 13.                          |
44| space               | number \| string                          | No  | Spacing between list items. This parameter only affects the spacing between list items, but not spacing between the header and list items or between the footer and list items.<br>Default value: **0**<br>Unit: vp<br>**Atomic service API**: This API can be used in atomic services since API version 11. |
45| style<sup>10+</sup> | [ListItemGroupStyle](#listitemgroupstyle10) | No  | Style of the list item group.<br>Default value: **ListItemGroupStyle.NONE**<br>If this parameter is set to **ListItemGroupStyle.NONE**, no style is applied.<br>When **ListItemGroupStyle.CARD** is used, you are advised to pair it with **ListItemStyle.CARD** from [ListItem](ts-container-listitem.md) to apply the default card style.<br>In the card style, the default specifications for the **ListItemGroup** are as follows: horizontal margin of 12 vp on both left and right sides, and vertical as well as horizontal padding of 4 vp.<br>In the default card style, list items can be in focus, hover, press, selected, or disable style depending on their state.<br>**NOTE**<br>In the card style, by default, the list runs along the vertical axis, that is, **listDirection** is at **Axis.Vertical**. If **listDirection** is set to **Axis.Horizontal**, a disordered display may result. The **alignListItem** attribute of the list is set to **ListItemAlign.Center** by default, which aligns the list items in the center.<br>**Atomic service API**: This API can be used in atomic services since API version 11.|
46
47## Attributes
48
49### divider
50
51divider(value: [ListDividerOptions](ts-container-list.md#listdivideroptions14) | null)
52
53Sets the style of the divider for the list items. By default, there is no divider.
54
55**strokeWidth**, **startMargin**, and **endMargin** cannot be set in percentage.
56
57When a list item has [polymorphic styles](ts-universal-attributes-polymorphic-style.md) applied, the dividers above and below the pressed child component are not rendered.
58
59**Atomic service API**: This API can be used in atomic services since API version 11.
60
61**System capability**: SystemCapability.ArkUI.ArkUI.Full
62
63**Parameters**
64
65| Name| Type                                                        | Mandatory| Description                                                        |
66| ------ | ------------------------------------------------------------ | ---- | ------------------------------------------------------------ |
67| value  | [ListDividerOptions](ts-container-list.md#listdivideroptions14) \| null | Yes  | Style of the divider for the list items.<br> Default value: **null**|
68
69### childrenMainSize<sup>12+</sup>
70
71childrenMainSize(value: ChildrenMainSize)
72
73Sets the size information of the child components of a **ListItemGroup** component along the main axis.
74
75**Atomic service API**: This API can be used in atomic services since API version 12.
76
77**System capability**: SystemCapability.ArkUI.ArkUI.Full
78
79**Parameters**
80
81| Name    | Type  | Mandatory| Description                           |
82| ---------- | ------ | ---- | ------------------------------- |
83| value | [ChildrenMainSize](ts-container-scrollable-common.md#childrenmainsize12) | Yes  | Size information of all list items along the main axis, provided through a **ChildrenMainSize** object to the **ListItemGroup** component.<br>The provided size along the main axis must be consistent with the actual size of the child components on the main axis.<br>For the setting to take effect, this attribute must be used together with the **childrenMainSize** attribute of the **List** component.<br>Any changes in size or additions/removals of child components must be communicated to the **ListItemGroup** component through the **ChildrenMainSize** object method.|
84
85## ListItemGroupStyle<sup>10+</sup>
86
87**Atomic service API**: This API can be used in atomic services since API version 11.
88
89**System capability**: SystemCapability.ArkUI.ArkUI.Full
90
91| Name| Value | Description            |
92| ---- | ---- | ------------------ |
93| NONE | 0 | No style.          |
94| CARD | 1 | Default card style.|
95
96
97
98## Example
99
100### Example 1: Setting a Sticky Header and Footer
101
102This example demonstrates how to set a sticky header and footer using the **stick** attribute.
103
104```ts
105// xxx.ets
106@Entry
107@Component
108struct ListItemGroupExample {
109  private timeTable: TimeTable[] = [
110    {
111      title: 'Monday',
112      projects: ['Language', 'Math', 'English']
113    },
114    {
115      title: 'Tuesday',
116      projects: ['Physics', 'Chemistry', 'Biology']
117    },
118    {
119      title: 'Wednesday',
120      projects: ['History', 'Geography', 'Politics']
121    },
122    {
123      title: 'Thursday',
124      projects: ['Art', 'Music', 'Sports']
125    }
126  ]
127
128  @Builder
129  itemHead(text: string) {
130    Text(text)
131      .fontSize(20)
132      .backgroundColor(0xAABBCC)
133      .width("100%")
134      .padding(10)
135  }
136
137  @Builder
138  itemFoot(num: number) {
139    Text('Total lessons: ' + num)
140      .fontSize(16)
141      .backgroundColor(0xAABBCC)
142      .width("100%")
143      .padding(5)
144  }
145
146  build() {
147    Column() {
148      List({ space: 20 }) {
149        ForEach(this.timeTable, (item: TimeTable) => {
150          ListItemGroup({ header: this.itemHead(item.title), footer: this.itemFoot(item.projects.length) }) {
151            ForEach(item.projects, (project: string) => {
152              ListItem() {
153                Text(project)
154                  .width("100%")
155                  .height(100)
156                  .fontSize(20)
157                  .textAlign(TextAlign.Center)
158                  .backgroundColor(0xFFFFFF)
159              }
160            }, (item: string) => item)
161          }
162          .divider({ strokeWidth: 1, color: Color.Blue }) // Divider between lines
163        })
164      }
165      .width('90%')
166      .sticky(StickyStyle.Header | StickyStyle.Footer)
167      .scrollBar(BarState.Off)
168    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
169  }
170}
171
172interface TimeTable {
173  title: string;
174  projects: string[];
175}
176```
177
178![en-us_image_0000001219864159](figures/en-us_image_listitemgroup.gif)
179
180### Example 2: Setting the Card Style
181
182This example illustrates the card-style effect of the **ListItemGroup** component.
183
184```ts
185// xxx.ets
186@Entry
187@Component
188struct ListItemGroupExample2 {
189  private arr: ArrObject[] = [
190    {
191      style: ListItemGroupStyle.CARD,
192      itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.CARD]
193    },
194    {
195      style: ListItemGroupStyle.CARD,
196      itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE]
197    },
198    {
199      style: ListItemGroupStyle.CARD,
200      itemStyles: [ListItemStyle.CARD, ListItemStyle.NONE, ListItemStyle.CARD]
201    },
202    {
203      style: ListItemGroupStyle.NONE,
204      itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE]
205    }
206  ]
207
208  build() {
209    Column() {
210      List({ space: "4vp", initialIndex: 0 }) {
211        ForEach(this.arr, (item: ArrObject, index?: number) => {
212          ListItemGroup({ style: item.style }) {
213            ForEach(item.itemStyles, (itemStyle: number, itemIndex?: number) => {
214              ListItem({ style: itemStyle }) {
215                if (index != undefined && itemIndex != undefined) {
216                  Text("Item " + (itemIndex + 1) +" in group " + (index + 1))
217                    .width("100%")
218                    .textAlign(TextAlign.Center)
219                }
220              }
221            }, (item: string) => item)
222          }
223        })
224      }
225      .width('100%')
226      .multiSelectable(true)
227      .backgroundColor(0xDCDCDC)
228    }
229    .width('100%')
230    .padding({ top: 5 })
231  }
232}
233
234interface ArrObject {
235  style: number;
236  itemStyles: number[];
237}
238```
239![ListItemGroupStyle](figures/listItemGroup2.jpeg)
240
241### Example 3: Setting Header and Footer
242
243This example demonstrates how to set the header and footer using **ComponentContent**.
244
245```ts
246// xxx.ets
247import { ComponentContent } from '@kit.ArkUI';
248
249interface TimeTable {
250  title: string;
251  projects: string[];
252}
253
254class HeadBuilderParams {
255  text: string | Resource;
256  constructor(text: string | Resource) {
257    this.text = text;
258  }
259}
260
261class FootBuilderParams {
262  num: number | Resource;
263  constructor(num: number | Resource) {
264    this.num = num;
265  }
266}
267
268@Builder
269function itemHead(params: HeadBuilderParams) {
270  Text(params.text)
271    .fontSize(20)
272    .height('48vp')
273    .width("100%")
274    .padding(10)
275    .backgroundColor($r('sys.color.background_tertiary'))
276}
277
278@Builder
279function itemFoot(params: FootBuilderParams) {
280  Text('Total lessons:' + params.num)
281    .fontSize(20)
282    .height('48vp')
283    .width("100%")
284    .padding(10)
285    .backgroundColor($r('sys.color.background_tertiary'))
286}
287
288@Component
289struct MyItemGroup {
290  item: TimeTable = { title: "", projects: [] }
291  header?: ComponentContent<HeadBuilderParams> = undefined
292  footer?: ComponentContent<FootBuilderParams> = undefined
293  headerParam = new HeadBuilderParams(this.item.title)
294  footerParam = new FootBuilderParams(this.item.projects.length)
295
296  aboutToAppear(): void {
297    this.header = new ComponentContent(this.getUIContext(), wrapBuilder(itemHead), this.headerParam)
298    this.footer = new ComponentContent(this.getUIContext(), wrapBuilder(itemFoot), this.footerParam)
299  }
300  GetHeader() {
301    this.header?.update(new HeadBuilderParams(this.item.title));
302    return this.header;
303  }
304
305  GetFooter() {
306    this.footer?.update(new FootBuilderParams(this.item.projects.length));
307    return this.footer;
308  }
309
310  build() {
311    ListItemGroup({
312      headerComponent: this.GetHeader(),
313      footerComponent: this.GetFooter()
314    }) {
315      ForEach(this.item.projects, (project: string) => {
316        ListItem() {
317          Text(project)
318            .width("100%")
319            .height(100)
320            .fontSize(20)
321            .textAlign(TextAlign.Center)
322        }
323      }, (item: string) => item)
324    }
325    .divider({ strokeWidth: 1, color: Color.Blue }) // Divider between lines
326  }
327}
328
329@Entry
330@Component
331struct ListItemGroupExample {
332  @State timeTable: TimeTable[] = [
333    {
334      title: 'Monday',
335      projects: ['Language', 'Math', 'English']
336    },
337    {
338      title: 'Tuesday',
339      projects: ['Physics', 'Chemistry', 'Biology']
340    },
341    {
342      title: 'Wednesday',
343      projects: ['History', 'Geography', 'Politics', 'Sports']
344    },
345    {
346      title: 'Thursday',
347      projects: ['Art', 'Music']
348    }
349  ]
350
351  build() {
352    Column() {
353      Button("Update").width(100).height(50).onClick(() => {
354        this.timeTable[0] = {
355          title: 'Monday after update',
356          projects: ['Language', 'Physics', 'History', 'Art']
357        }
358      })
359      List({ space: 20 }) {
360        ForEach(this.timeTable, (item: TimeTable) => {
361          MyItemGroup({ item: item })
362        })
363      }
364      .layoutWeight(1)
365      .sticky(StickyStyle.Header | StickyStyle.Footer)
366      .scrollBar(BarState.Off)
367    }
368    .backgroundColor($r('sys.color.background_primary'))
369  }
370}
371```
372
373![en-us_image_listitemgroup_example03](figures/en-us_image_listitemgroup_example03.gif)
374