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 and, if not otherwise specified, takes up the entire width of the **List**.
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**, the [universal attribute height](ts-universal-attributes-size.md) is not effective. 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**, the [universal attribute width](ts-universal-attributes-size.md) is not effective. 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. That is, their **editable** attribute does not take effect.
13> - The **ListItemGroup** does not respond to the **direction** attribute for setting its layout direction; instead, it aligns with 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**Atomic service API**: This API can be used in atomic services since API version 11.
37
38**System capability**: SystemCapability.ArkUI.ArkUI.Full
39
40| Name             | Type                                           | Mandatory| Description                                                    |
41| ------------------- | --------------------------------------------------- | ---- | ------------------------------------------------------------ |
42| 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.              |
43| 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.              |
44| space               | number \| string                          | No  | Spacing between list items. This parameter is valid only between list items, but not between the header and list item or between the footer and list item.<br>Default value: **0**<br>Unit: vp |
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.|
46
47## Attributes
48
49### divider
50
51divider(value: {strokeWidth: Length; color?: ResourceColor; startMargin?: Length; endMargin?: Length;} | 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  | {<br>strokeWidth: [Length](ts-types.md#length),<br>color?:[ResourceColor](ts-types.md#resourcecolor),<br>startMargin?: [Length](ts-types.md#length),<br>endMargin?: [Length](ts-types.md#length)<br>} \| null | Yes  | Style of the divider for the list items.<br>- **strokeWidth**: stroke width of the divider.<br>- **color**: color of the divider.<br> Default value: **0x08000000**<br>- **startMargin**: distance between the divider and the start edge of the list.<br>Default value: **0**, in vp<br>- **endMargin**: distance between the divider and the end edge of the list.<br>Default value: **0**, in vp|
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>1. The provided size along the main axis must be consistent with the actual size of the child components on the main axis.<br>2. For the setting to take effect, this attribute must be used together with the **childrenMainSize** attribute of the **List** component.<br>3. 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
101
102```ts
103// xxx.ets
104@Entry
105@Component
106struct ListItemGroupExample {
107  private timeTable: TimeTable[] = [
108    {
109      title: 'Monday',
110      projects: ['Language', 'Math', 'English']
111    },
112    {
113      title: 'Tuesday',
114      projects: ['Physics', 'Chemistry', 'Biologics']
115    },
116    {
117      title: 'Wednesday',
118      projects: ['History', 'Geography', 'Politics']
119    },
120    {
121      title: 'Thursday',
122      projects: ['Art', 'Music', 'Sports']
123    }
124  ]
125
126  @Builder
127  itemHead(text: string) {
128    Text(text)
129      .fontSize(20)
130      .backgroundColor(0xAABBCC)
131      .width("100%")
132      .padding(10)
133  }
134
135  @Builder
136  itemFoot(num: number) {
137    Text(''Total lessons:'+ num")
138      .fontSize(16)
139      .backgroundColor(0xAABBCC)
140      .width("100%")
141      .padding(5)
142  }
143
144  build() {
145    Column() {
146      List({ space: 20 }) {
147        ForEach(this.timeTable, (item: TimeTable) => {
148          ListItemGroup({ header: this.itemHead(item.title), footer: this.itemFoot(item.projects.length) }) {
149            ForEach(item.projects, (project: string) => {
150              ListItem() {
151                Text(project)
152                  .width("100%")
153                  .height(100)
154                  .fontSize(20)
155                  .textAlign(TextAlign.Center)
156                  .backgroundColor(0xFFFFFF)
157              }
158            }, (item: string) => item)
159          }
160          .divider ({ strokeWidth: 1,color:Color.Blue }) // Divider between lines
161        })
162      }
163      .width('90%')
164      .sticky(StickyStyle.Header | StickyStyle.Footer)
165      .scrollBar(BarState.Off)
166    }.width('100%').height('100%').backgroundColor(0xDCDCDC).padding({ top: 5 })
167  }
168}
169
170interface TimeTable {
171  title: string;
172  projects: string[];
173}
174```
175
176![en-us_image_0000001219864159](figures/en-us_image_listitemgroup.gif)
177
178### Example 2
179
180```ts
181// xxx.ets
182@Entry
183@Component
184struct ListItemGroupExample2 {
185  private arr: ArrObject[] = [
186    {
187      style: ListItemGroupStyle.CARD,
188      itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.CARD]
189    },
190    {
191      style: ListItemGroupStyle.CARD,
192      itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE]
193    },
194    {
195      style: ListItemGroupStyle.CARD,
196      itemStyles: [ListItemStyle.CARD, ListItemStyle.NONE, ListItemStyle.CARD]
197    },
198    {
199      style: ListItemGroupStyle.NONE,
200      itemStyles: [ListItemStyle.CARD, ListItemStyle.CARD, ListItemStyle.NONE]
201    }
202  ]
203
204  build() {
205    Column() {
206      List({ space: "4vp", initialIndex: 0 }) {
207        ForEach(this.arr, (item: ArrObject, index?: number) => {
208          ListItemGroup({ style: item.style }) {
209            ForEach(item.itemStyles, (itemStyle: number, itemIndex?: number) => {
210              ListItem({ style: itemStyle }) {
211                if (index != undefined && itemIndex != undefined) {
212                  Text("Item" + (itemIndex + 1) +" in group" + (index + 1) +" ")
213                    .width("100%")
214                    .textAlign(TextAlign.Center)
215                }
216              }
217            }, (item: string) => item)
218          }
219        })
220      }
221      .width('100%')
222      .multiSelectable(true)
223      .backgroundColor(0xDCDCDC)
224    }
225    .width('100%')
226    .padding({ top: 5 })
227  }
228}
229
230interface ArrObject {
231  style: number;
232  itemStyles: number[];
233}
234```
235![ListItemGroupStyle](figures/listItemGroup2.jpeg)
236