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 example.

Virtual scrolling

A long list of 10,000 rows. Set virtual and height to enable virtual scrolling, so only the rows in view are rendered.

Grouping and sticky headers

Use group to derive a group key from each item and render group headers. With sticky enabled, the current group header sticks to the top while scrolling.

Rich content

itemRender can render arbitrarily rich content, and rows do not need the same height.

Drag sorting

Implement drag sorting for list items by integrating the third-party library dnd-kit.

Infinite loading

Detect in onScroll that the list is about to reach the bottom, then load the next page on demand for endless scrolling. Combined with virtual, only the rows in view are rendered no matter how much data piles up.

Custom semantic dom styling

Customize the semantic DOM styles of Listy with classNames and styles.

API

Listy are exported from @ceebee/ui/client.

Listy

Property	Description	Type	Default	Version
`classNames`	Semantic class names	`{ root?, item?, groupHeader? }`	`-`	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
`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	Default	Version
`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

Property	Description	Type	Default	Version
`scrollTo`	Scroll to a position, an item, or a group	`(config?: ListyScrollToConfig) => void`	`—`	—
`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	`—`	`—`	—