# List

- Page: https://jiguang132.com/resources/arco-design/docs/list
- Resource: Arco Design (https://jiguang132.com/resources/arco-design.md)
- All guides: https://jiguang132.com/resources/arco-design/docs.md

The most basic list display, which can carry text/pictures/paragraphs, and is often used in the data display page.

## Install

```bash
npm install @arco-design/web-react@2.66.18
```

Import `@arco-design/web-react/dist/css/arco.css` at the entry and set the locale with `ConfigProvider`. React 19 projects must also import `@arco-design/web-react/es/_util/react-19-adapter` first, or imperative APIs such as Message and Modal cannot render.

## Examples

- **Basic**: List can carry text, pictures, and paragraphs, and is often used to display data.
- **Size**: There are three sizes (`small` `default` `large`) that you can select according to your need.
- **With Meta**: Use `List.Item.Meta` to quickly specify avatar, title, and text.
- **With Actions**: Use `actions` to add operation items to the list.
- **Vertical List**: This is an example including paging, content on the right, and list operations.
- **Grid List**: Use `grid.span` to set the number of columns expected to occupy.
- **Responsive List Grid**: Dynamically set the number of columns occupied by each item through parameters such as `grid.sm`. Be careful not to set `grid.span` at this time.
- **Scroll Loading**: You can set `onReachBottom` to dynamically loading data when the list is scrolling. If `onReachBottom` cannot meet the requirements, you can customize the list scrolling monitor function through `onListScroll`, at this time the default monitor function will be invalid.
- **Infinite List**: By specifying `virtualListProps` to turn on the virtual list, high performance can be obtained when a large amount of data is used. When using a virtual list, if the height of the list items varies greatly, it may cause blank space in the viewport when scrolling, which can be solved by setting `virtualListProps.itemHeight`. `itemHeight` is used to calculate the actual number of DOM nodes that need to be rendered (viewportHeight / itemHeight). The smaller the value, the more DOM nodes actually rendered, and the performance overhead will increase. **Because the virtual list uses the `ref` of ListItem internally, if you return a custom function component through `render`, please use `React.forwardRef` to wrap it.**

Examples come from the official Arco Design repository (MIT) at the commit published as npm 2.66.18. Some use online images or upload endpoints; network requests are disabled in previews.

## API

### List

|Property|Description|Type|DefaultValue|Version|
|---|---|---|---|---|
|bordered|Whether to render border|boolean |`true`|-|
|hoverable|Whether list items have hover style|boolean |`-`|2.9.0|
|loading|Whether to show a loading indicator while the contents of the list are being fetched|boolean |`-`|-|
|split|Whether to render the split under the list item|boolean |`true`|-|
|defaultCurrent|To set default current page|number |`1`|-|
|offsetBottom|The distance threshold to trigger the `onReachBottom`|number |`0`|-|
|throttleDelay|Interval of throttle for `onListScroll`|number |`500`|-|
|size|Size of List|'small' \| 'default' \| 'large' |`-`|-|
|children|Child element of List. when dataSource and render exist, do not use this parameter|ReactNode |`-`|-|
|footer|List footer|ReactNode |`-`|-|
|header|List header|ReactNode |`-`|-|
|noDataElement|Content displayed when there is no data|ReactNode |`-`|-|
|scrollLoading|Set the content to be at the list bottom when you load data during scrolling|string \| ReactNode |`-`|-|
|className|Additional css class|string \| string[] |`-`|-|
|dataSource|Data source for list rendering. When `children` exist, this parameter can be omitted (`dataSource` has higher priority)|T[] |`-`|-|
|grid|The grid type of list|[ListGridProps](#listgridprops) |`-`|`column` in 2.20.0|
|listRef|Reference to the current list|MutableRefObject<[ListHandle](#listhandle)> |`-`|2.20.0|
|pagination|Whether to divide into pages, you can also pass in the configuration of `Pagination`|boolean \| [PaginationProps](pagination#pagination) |`-`|-|
|style|Additional style|CSSProperties |`-`|-|
|virtualListProps|Pass the virtual-list properties, pass in this parameter to turn on virtual scrolling|[AvailableVirtualListProps](#availablevirtuallistprops) |`-`|2.11.0|
|wrapperClassName|The additional css class to wrapper element|string \| string[] |`-`|-|
|wrapperStyle|The additional css style to wrapper element|CSSProperties |`-`|-|
|onListScroll|Callback when list is scrolling. When onReachBottom cannot meet your usage, can customize scroll monitor function|(elem: Element) => void |`-`|-|
|onReachBottom|Callback when the list scroll to the bottom|(currentPage: number) => void |`-`|-|
|render|Customize list item when using dataSource|(item: T, index: number) => ReactNode |`-`|-|

### List.Item

|Property|Description|Type|DefaultValue|
|---|---|---|---|
|actionLayout|The position of the list operation group. `horizontal` - right, `vertical` - below.|'horizontal' \| 'vertical' |`horizontal`|
|extra|The extra content of list item which is on the far right|ReactNode |`-`|
|actions|The list operation group of list item|ReactNode[] |`-`|
|className|Additional css class|string \| string[] |`-`|
|style|Additional style|CSSProperties |`-`|

### List.Item.Meta

|Property|Description|Type|DefaultValue|
|---|---|---|---|
|avatar|The avatar of list item|ReactNode |`-`|
|description|The description of list item|ReactNode |`-`|
|title|The title of list item|ReactNode |`-`|
|className|Additional css class|string \| string[] |`-`|
|style|Additional style|CSSProperties |`-`|

### ListGridProps

```js
type ListGridProps = {
  column?: number;
} & Pick<RowProps, "gutter" | "justify" | "align"> &
  Pick<
    ColProps,
    "span" | "offset" | "order" | "pull" | "push" | GridResponsiveBreakpoint
  >;
```

### ListHandle

```js
export type ListHandle = {
  dom: HTMLDivElement;
  scrollIntoView: (index: number) => void;
};
```

### AvailableVirtualListProps

```js
export type AvailableVirtualListProps = Pick<
  VirtualListProps<any>,
  | "height"
  | "itemHeight"
  | "threshold"
  | "isStaticItemHeight"
  | "scrollOptions"
  | "onScroll"
  | "wrapperChild"
>;
```

### `<ListGridProps>`

|Property|Description|Type|Default|
|---|:---:|:---:|---:|
|gutter|Spacing between grids|`number`|`-`|
|span|Raster number of cells to occupy|`number`|`-`|
|xs|`span` for `xs`|`number`|`-`|
|sm|`span` for `sm`|`number`|`-`|
|md|`span` for `md`|`number`|`-`|
|lg|`span` for `lg`|`number`|`-`|
|xl|`span` for `xl`|`number`|`-`|
|xxl|`span` for `xxl`|`number`|`-`|

### VirtualListProps

|Property|Description|Type|Default|
|---|:---:|:---:|---:|
|height|Viewable area height (`2.11.0` starts to support `string` type such as `80%`)|`number`| `200` |
|threshold|The threshold of the number of elements that automatically enable virtual scrolling, pass in `null` to disable virtual scrolling.|`number` \| `null`| `100` |
|isStaticItemHeight|Whether it is a static element of the same height|`boolean`|`true`|

---

Index of all JGuang resources: https://jiguang132.com/llms.txt