Listy

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

Property	Description	Type	Default	Version	Global Config
classNames	Semantic class names	`{ root?, item?, groupHeader? }`	-	6.6.0	6.6.0
group	Grouping config, see 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

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

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

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.