The useList suite provides a set of hooks designed to create stateless List components. The core architectural pattern is that the hooks manage all complex logic (state, filtering, keyboard navigation, tree structures), while you are responsible for implementing the "dumb" view components.
Core Abstractions
Hooks (Logic):
useList: The primary hook for managing list state.useListKeydown: Handles keyboard navigation for the list.useListFilter: Manages filtering logic for list items.
Components (View only):
ListItemView: A stateless component for rendering an individual item.ListContainerView: A container component for the list.ListItemExpandIcon: An icon used to indicate expandable tree items.ListRecursiveRenderer: A component specifically for rendering nested/tree structures.
Utilities:
getListItemClickHandler: Generates click handlers for list items.getItemRenderState: Computes the props needed for a ListItemView based on the current list state.scrollToListItem: Utility for scrolling to a specific item.computeItemSize: Calculates item dimensions.getListParsedState and getListItemQa: State and QA utilities.
import {
type unstable_ListItemId as ListItemId,
type unstable_ListItemType as ListItemType,
unstable_ListContainerView as ListContainerView,
unstable_ListItemView as ListItemView,
unstable_getItemRenderState as getItemRenderState,
unstable_useList as useList,
unstable_useListKeydown as useListKeydown,
unstable_useListState as useListState,
} from '@gravity-ui/uikit/unstable';
const items: ListItemType<string>[] = ['one', 'two', 'free', 'four', 'five'];
function List() {
const containerRef = React.useRef<HTMLDivElement>(null);
const list = useList({items});
const onItemClick = getListItemClickHandler({list, multiple: true});
useListKeydown({onItemClick, containerRef, list});
return (
<ListContainerView ref={containerRef}>
{list.structure.items.map((_, i) => {
const {props} = getItemRenderState({
id: String(i),
mapItemDataToContentProps: (title) => ({title}),
onItemClick,
list,
});
return <ListItemView key={i} {...props} />;
})}
</ListContainerView>
);
}
