Virtual list
A windowed list for thousands of rows: only the rows in view are in the page.
SourceStyles source@monoline/react 0.4.0Markdown for AI toolsstable
- 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
| Prop | Type | Default | Description |
|---|---|---|---|
aria-label required | string | – | Required: names the list for screen readers. |
count required | number | – | How many rows the whole list has, rendered or not. |
itemHeight required | number | – | Height of every row in pixels. All rows share it. |
height required | number | – | Height of the scrolling window in pixels. |
overscan | number | 4 | Extra 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
| Class | Stylesheet |
|---|---|
.virtual-list | virtual-list.css |
.virtual-list-body | virtual-list.css |
.virtual-list-row | virtual-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
| Keys | Action |
|---|---|
| Home / End | Move focus and scroll the row into view |