Playground

Virtual list

A windowed list for thousands of rows: only the rows in view are in the page.

  • Built on native elements
  • role=list with listitem rows; every row carries aria-posinset and aria-setsize so the position in the full list is announced.
  • Roving tabindex: one row is in the tab order. ArrowUp/ArrowDown, PageUp/PageDown, Home and End move focus and scroll the row into view.
  • The list needs an aria-label.
  • Styles in one file: virtual-list.css

Import

import '@monoline/css';
import {VirtualList} from '@monoline/react';

Not installed yet? Pick a route.

Copies the source and its styles into your project.

npx monoline add virtual-list

Usage

import {VirtualList} from '@monoline/react';

<VirtualList
  aria-label="Ten thousand rows"
  count={10000}
  itemHeight={32}
  height={192}
  renderItem={(i) => <span className="virtual-list-cell">Row {i + 1}</span>}
/>

Examples

10,000 rows

Only about a dozen rows exist in the page. Tab in, then use the arrow keys, Home and End.

Props

VirtualListProps

PropTypeDefaultDescription
aria-label requiredstring–Required: names the list for screen readers.
count requirednumber–How many rows the whole list has, rendered or not.
itemHeight requirednumber–Height of every row in pixels. All rows share it.
height requirednumber–Height of the scrolling window in pixels.
overscannumber4Extra rows rendered above and below the visible ones, so fast scrolling shows no blanks. Default 4.
renderItem required(index: number) => ReactNode–Returns the content of row `index`. Only called for rows in or near the window.

Data Attributes

State is exposed through attributes. Style it with these selectors, not with class toggles.

This component sets no state attributes.

CSS classes

ClassStylesheet
.virtual-listvirtual-list.css
.virtual-list-bodyvirtual-list.css
.virtual-list-rowvirtual-list.css

Customization

Style it with the kit's tokens in your own CSS, loaded after @monoline/css. Prefer the attributes above over extra classes. See Theming for every token.

app.css
.virtual-list {
  border-color: var(--accent);
}

Accessibility

  • role=list with listitem rows; every row carries aria-posinset and aria-setsize so the position in the full list is announced.
  • Roving tabindex: one row is in the tab order. ArrowUp/ArrowDown, PageUp/PageDown, Home and End move focus and scroll the row into view.
  • The list needs an aria-label.

Keyboard

KeysAction
Home / EndMove focus and scroll the row into view