# Listy

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

A high-performance list that supports grouping and can virtualize long data sets.


## When To Use

- When you need to render a long list without paying the cost of mounting every row — enable `virtual` to render only the rows in view.
- When the list needs grouped sections with sticky headers.
- When you need imperative control over scroll position (jump to an item, a group, or a pixel offset).

## Examples


- Basic · `basic`
- Virtual scrolling · `virtual`
- Grouping and sticky headers · `group`
- Rich content · `rich`
- Drag sorting · `drag-sorting`
- Infinite loading · `infinite`
- Custom semantic dom styling · `style-class`


## API

> Listy component is available since `antd@6.6.0`.

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

| Property | Description | Type | Default | Version | [Global Config](/components/config-provider#component-config) |
| --- | --- | --- | --- | --- | --- |
| classNames | Semantic class names | `{ root?, item?, groupHeader? }` | - | 6.6.0 | 6.6.0 |
| group | Grouping config, see [Group](#group) below | `Group<T, K>` | - | 6.6.0 | × |
| height | Height of the scroll container; content scrolls when it overflows | number | - | 6.6.0 | × |
| itemRender | Render a single row | `(item: T, index: number) => ReactNode` | - | 6.6.0 | × |
| items | Data source of the list | `T[]` | `[]` | 6.6.0 | × |
| rowKey | Unique key of an item, a field name or a getter | `keyof T \| (item: T) => Key` | - | 6.6.0 | × |
| sticky | Whether group headers stick to the top | boolean | false | 6.6.0 | × |
| styles | Semantic inline styles | `{ root?, item?, groupHeader? }` | - | 6.6.0 | 6.6.0 |
| virtual | Whether to enable virtual scrolling, rendering only rows in view, requires `height` | boolean | false | 6.6.0 | × |
| onScroll | Native scroll event handler | `React.UIEventHandler<HTMLElement>` | - | 6.6.0 | × |

### Group

| Property | Description | Type |
| --- | --- | --- |
| key | Compute the group key an item belongs to; items with the same key are grouped together | `(item: T) => K` |
| title | Render the group header; receives the group key and its items | `(groupKey: K, items: T[]) => ReactNode` |

### Ref

| Name     | Description                               | Type                                     |
| -------- | ----------------------------------------- | ---------------------------------------- |
| scrollTo | Scroll to a position, an item, or a group | `(config?: ListyScrollToConfig) => void` |

`ListyScrollToConfig` is one of:

| Shape                           | Description                                     |
| ------------------------------- | ----------------------------------------------- |
| number                          | Scroll to a pixel offset (scrollTop)            |
| `{ top?, left? }`               | Scroll to an absolute pixel position            |
| `{ key, align?, offset? }`      | Scroll to the item whose `rowKey` matches `key` |
| `{ groupKey, align?, offset? }` | Scroll to a group header                        |

`align` is `'top' | 'bottom' | 'auto'`; `offset` is an extra pixel offset applied after alignment.

## Semantic DOM

| Semantic node | Native description | Version |
| --- | --- | --- |
| `root` | Root element, the scroll container, with font and relative positioning | — |
| `item` | Item element, with padding, split line and hover background | — |
| `groupHeader` | Group header element, with sticky positioning and background color | — |

Semantic description source: `vendor/components/listy/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 |
| --- | --- | --- |
| `itemPaddingBlock` | `number` | Vertical padding of a list item. |
| `itemPaddingInline` | `number` | Horizontal padding of a list item. |

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

```ts
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 } from '../../theme/internal';

export interface ComponentToken {
  /**
   * @nameZH 列表项纵向内间距
   * @nameEN Item Vertical Padding
   * @desc 列表项的纵向内间距。
   * @descEN Vertical padding of a list item.
   */
  itemPaddingBlock: number;
  /**
   * @nameZH 列表项横向内间距
   * @nameEN Item Horizontal Padding
   * @desc 列表项的横向内间距。
   * @descEN Horizontal padding of a list item.
   */
  itemPaddingInline: number;
}

type ListyToken = FullToken<'Listy'>;
```


## 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/listy/index.tsx`
- `vendor/components/listy/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