# List

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

Basic list display, which can carry text, lists, pictures, paragraphs.


## When To Use

A list can be used to display content related to a single subject. The content can consist of multiple elements of varying type and size.


:::warning{title=Deprecated Notice}
List component has been deprecated. Will be removed in the next major version. Please use [Listy](/components/listy) instead. See [How do I migrate off List?](#faq-migrate-from-list).
:::

## Examples


- Simple list · `simple`
- Basic list · `basic`
- Load more · `loadmore`
- Vertical · `vertical`
- Pagination Settings · `pagination`
- Grid · `grid`

- Responsive grid list · `responsive`
- Scrolling loaded · `infinite-load`
- Drag sorting · `drag-sorting`
- Drag sorting with handler · `drag-sorting-handler`
- Grid Drag sorting · `grid-drag-sorting`
- Grid Drag sorting with handler · `grid-drag-sorting-handler`
- virtual list · `virtual-list`



## API

Common props ref：[Common props](#jguang-common-props)

### List

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| bordered | Toggles rendering of the border around the list | boolean | false |  | × |
| dataSource | DataSource array for list | any\[] | - |  | × |
| footer | List footer renderer | ReactNode | - |  | × |
| grid | The grid type of list. You can set grid to something like {gutter: 16, column: 4} | [object](#list-grid-props) | - |  | × |
| header | List header renderer | ReactNode | - |  | × |
| itemLayout | The layout of list | `horizontal` \| `vertical` | `horizontal` |  | × |
| loading | Shows a loading indicator while the contents of the list are being fetched | boolean \| [SpinProps](/components/spin/#api) ([more](https://github.com/ant-design/ant-design/issues/8659)) | false |  | × |
| loadMore | Shows a load more content | ReactNode | - |  | × |
| locale | The i18n text including empty text | object | {emptyText: `No Data`} |  | × |
| pagination | Pagination [config](/components/pagination/), hide it by setting it to false | boolean \| object | false |  | × |
| renderItem | Customize list item when using `dataSource` | (item: T, index: number) => ReactNode | - |  | × |
| rowKey | Item's unique value, could be an Item's key which holds a unique value of type `React.Key` or function that receives Item and returns a `React.Key` | `keyof` T \| (item: T) => `React.Key` | `"key"` |  | × |
| size | Size of list | `default` \| `large` \| `small` | `default` |  | × |
| split | Toggles rendering of the split under the list item | boolean | true |  | × |

### pagination

Properties for pagination.

| Property | Description                               | Type                         | Default  |
| -------- | ----------------------------------------- | ---------------------------- | -------- |
| position | The specify the position of `Pagination`  | `top` \| `bottom` \| `both`  | `bottom` |
| align    | The specify the alignment of `Pagination` | `start` \| `center` \| `end` | `end`    |

More about pagination, please check [`Pagination`](/components/pagination/).

### List grid props

| Property | Description              | Type   | Default | Version |
| -------- | ------------------------ | ------ | ------- | ------- |
| column   | The column of grid       | number | -       |         |
| gutter   | The spacing between grid | number | 0       |         |
| xs       | `<576px` column of grid  | number | -       |         |
| sm       | `≥576px` column of grid  | number | -       |         |
| md       | `≥768px` column of grid  | number | -       |         |
| lg       | `≥992px` column of grid  | number | -       |         |
| xl       | `≥1200px` column of grid | number | -       |         |
| xxl      | `≥1600px` column of grid | number | -       |         |
| xxxl     | `≥1920px` column of grid | number | -       | 6.3.0   |

### List.Item

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| actions | The actions content of list item. If `itemLayout` is `vertical`, shows the content on bottom, otherwise shows content on the far right | Array&lt;ReactNode> | - |  | × |
| classNames | Semantic structure className | [`Record<actions \| extra, string>`](#semantic-dom) | - | 5.18.0 | 5.18.0 |
| extra | The extra content of list item. If `itemLayout` is `vertical`, shows the content on right, otherwise shows content on the far right | ReactNode | - |  | × |
| styles | Semantic DOM style | [`Record<actions \| extra, CSSProperties>`](#semantic-dom) | - | 5.18.0 | 5.18.0 |

### List.Item.Meta

| Property    | Description                  | Type      | Default | Version |
| ----------- | ---------------------------- | --------- | ------- | ------- |
| avatar      | The avatar of list item      | ReactNode | -       |         |
| description | The description of list item | ReactNode | -       |         |
| title       | The title of list item       | ReactNode | -       |         |

## Semantic DOM

| Semantic node | Native description | Version |
| --- | --- | --- |
| `extra` | set `extra` of List.Item | 5.18.0 |
| `actions` | set `actions` of List.Item | 5.18.0 |

Semantic description source: `vendor/components/list/demo/_semantic.tsx`

## Design Token

Types, inheritance and declarations retain the pinned native source. Defaults are computed by the native theme and may be overridden by ConfigProvider; this table does not invent static defaults.

| Token | Type | Native description |
| --- | --- | --- |
| `contentWidth` | `number \| string` | Width of content |
| `itemPaddingLG` | `string` | Padding of large item |
| `itemPaddingSM` | `string` | Padding of small item |
| `itemPadding` | `string` | Padding of item |
| `headerBg` | `string` | Background color of header |
| `footerBg` | `string` | Background color of footer |
| `emptyTextPadding` | `CSSProperties['padding']` | Padding of empty text |
| `metaMarginBottom` | `CSSProperties['marginBottom']` | Margin bottom of meta |
| `avatarMarginRight` | `CSSProperties['marginRight']` | Right margin of avatar |
| `titleMarginBottom` | `CSSProperties['marginBottom']` | Margin bottom of title |
| `descriptionFontSize` | `number` | Font size of description |

Declaration source: `vendor/components/list/style/index.ts`

```ts
import type { CSSProperties } from 'react';

import { unit } from '@ant-design/cssinjs';

import type { CSSObject } from '@ant-design/cssinjs';

import { resetComponent } from '../../style';

import type { FullToken, GenerateStyle, GetDefaultToken } from '../../theme/internal';

import { genStyleHooks, mergeToken } from '../../theme/internal';

export interface ComponentToken {
  /**
   * @desc 内容宽度
   * @descEN Width of content
   */
  contentWidth: number | string;
  /**
   * @desc 大号列表项内间距
   * @descEN Padding of large item
   */
  itemPaddingLG: string;
  /**
   * @desc 小号列表项内间距
   * @descEN Padding of small item
   */
  itemPaddingSM: string;
  /**
   * @desc 列表项内间距
   * @descEN Padding of item
   */
  itemPadding: string;
  /**
   * @desc 头部区域背景色
   * @descEN Background color of header
   */
  headerBg: string;
  /**
   * @desc 底部区域背景色
   * @descEN Background color of footer
   */
  footerBg: string;
  /**
   * @desc 空文本内边距
   * @descEN Padding of empty text
   */
  emptyTextPadding: CSSProperties['padding'];
  /**
   * @desc Meta 下间距
   * @descEN Margin bottom of meta
   */
  metaMarginBottom: CSSProperties['marginBottom'];
  /**
   * @desc 头像右间距
   * @descEN Right margin of avatar
   */
  avatarMarginRight: CSSProperties['marginRight'];
  /**
   * @desc 标题下间距
   * @descEN Margin bottom of title
   */
  titleMarginBottom: CSSProperties['marginBottom'];
  /**
   * @desc 描述文字大小
   * @descEN Font size of description
   */
  descriptionFontSize: number;
}

/**
 * @desc List 组件的 Token
 * @descEN Token for List component
 */
interface ListToken extends FullToken<'List'> {
  /**
   * @desc 列表项类名
   * @descEN Class name of list item
   */
  listBorderedCls: string;
  /**
   * @desc 最小高度
   * @descEN Minimum height
   */
  minHeight: number | string;
}
```

## FAQ {#faq}

### Is there a replacement for the deprecated List component? {#faq-listy-replacement}

Yes — please use [Listy](/components/listy), available since `antd@6.6.0`. It is the successor to List, with built-in capabilities such as virtual scrolling, sticky group headers and programmatic scrolling. It also supports flexible custom rendering, aiming to cover list needs across different scenarios.

### How do I migrate off List? {#faq-migrate-from-list}

Lists take different shapes in different scenarios, so it is hard to give a one-to-one migration guide. Thanks to the custom rendering capability of Listy, the preset structures in List can now be recomposed with plain JSX inside `itemRender`.

The mapping is as follows:

- **Data and rendering**: `dataSource` maps to `items`, `renderItem` maps to `itemRender`; `rowKey` keeps its meaning but is required in Listy and no longer defaults to the `key` field — pass `rowKey="key"` explicitly if you relied on the default. For large datasets, no third-party dependency is needed — turn on `virtual` with a `height` to get virtual scrolling.
- **Preset structures inside a row**: `List.Item`, `List.Item.Meta`, `actions`, `extra` can all be recomposed inside `itemRender`.
- **Structures outside the list**: put `header` and `footer` around Listy directly, wrap the list with [Spin](/components/spin) for `loading`, slice the data yourself and pass it to `items` together with [Pagination](/components/pagination) for `pagination`, and see the [infinite loading](/components/listy#listy-demo-infinite) demo for `loadMore`.
- **Styles**: adjust `bordered`, `split` and `size` through semantic DOM `classNames` / `styles` and Design Token; for `grid`, migrating to Listy is not recommended — use [Row / Col](/components/grid) with [Card](/components/card) to build the card layout instead.


## Shared native props {#jguang-common-props}


> Tips: The following generic properties apply to most antd components; those not supported are described separately.

| Property | Description | Type | Default |
| --- | --- | --- | --- |
| style | The additional style | CSSProperties | - |
| className | The additional css class | string | - |
| rootClassName | ClassName on the root element | string | - |
| autoFocus | Auto focus when component mounted, only effective for focusable elements like forms, links, etc. | boolean | false |


## Install and reproduce an example

```bash
npm install antd@6.6.5 @ant-design/icons@6.3.4 dayjs@1.11.23
```

Use ConfigProvider and native App; configure dayjs locale separately. Each example lists its complete source files and additional pinned dependencies in View code. Example names select demos, not universal component props. See the resource setup guide for theme, locale and SSR.

## Native type references

The source viewer includes unchanged native implementations and the following source declarations. Inherited types remain in their native packages. English source comments are preserved as code reference.

- `vendor/components/list/Item.tsx`
- `vendor/components/list/context.ts`
- `vendor/components/list/index.tsx`
- `vendor/components/list/style/index.ts`

## Source and license

https://github.com/ant-design/ant-design/tree/4a39f54842eade4e565ab336ef6097cd7e723cdd

Original bilingual prose and executable examples are retained. Website-only embeds and token tables are expanded locally. Ant Design is MIT; separately listed dependency notices also apply. Upload previews block outbound requests and do not provide a backend.

---

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