VirtualListItem

A single windowed list row: owns the role=listitem semantics with aria-posinset/aria-setsize position metadata, and composes ListItem for its chrome (leading icon, truncating label, end meta, trailing icon, selected check, destructive tone). Rendered by VirtualList.

Status: beta. Group: data-display. Markdown version: /design-system/components/virtual-list-item.md

When to use

VirtualListItem is the presentational row for VirtualList: ListItem chrome with an end-aligned meta slot, positioned by getItemProps inside a role="list" container. It carries no interactive semantics of its own.

When not to use

Do not render it outside a role=list container.
Do not duplicate ListItem chrome instead of composing it.
Do not put interactive semantics on the row; selection is visual only.

Look-alikes

The contract names no look-alike with a deciding condition.

Props

VirtualListItem props
Prop	Type	Default	Description	Required
`posInSet`	`number`	none	1-based position within the full collection (`aria-posinset`).	Yes
`setSize`	`number`	none	Total item count in the full collection (`aria-setsize`).	Yes
`style`	`React.CSSProperties`	none	Positioning style supplied by VirtualList (transform + block-size).	No

Variants

Available tones: neutral, destructive (default neutral).

Invalid combinations

The contract records no invalid combinations.

Keyboard

The contract records no keyboard interaction.

Rules

Every item under When not to use is a MUST NOT. MUST and SHOULD follow RFC 2119.

VirtualListItem rules
Level	Rule	How it is checked
MUST	ARIA: Role=listitem; must be rendered inside a role=list container (VirtualList's viewport)	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Aria-posinset/aria-setsize announce the true position within the full collection even though only the windowed rows are in the DOM.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	ARIA: Chrome is delegated to ListItem: icon/trailingIcon/check are decorative (aria-hidden), meta is exposed.	Not yet verified: no evidence record. WCAG 4.1.2.
MUST	Required stories produce no axe violations at the configured severity.	Automated by `npm run test:stories:matrix:ci`. WCAG 2.5.8.
MUST	The accessibility tree (role, name, state) matches the committed snapshot for every required story.	Automated by `npm run test:stories:matrix:ci`. WCAG 1.3.1, 4.1.2.
MUST	The component remains legible and operable under a real browser forced-colors: active pass.	Automated by `npm run test:stories:hc`.
MUST	A human completed an end-to-end accessibility review of this component.	Manual review, last on 2026-07-27.

Install and import

Install: npm install @digitaltableteur/react (version 0.9.1, restricted access on npm).
Import: import { VirtualListItem } from "@digitaltableteur/react";
Entry point: @digitaltableteur/react/content exports it too.
Styles: import @digitaltableteur/react/style.css once at the app boundary.