https://framer.com/m/VirtulList-G1tWnr.js

_ __ _ (_)___ ____/ /__ _____(_)___ _____ / / __ \ / __ / _ \/ ___/ / __ `/ __ \ / / /_/ / / /_/ / __(__ ) / /_/ / / / / /_/\____/ \__,_/\___/____/_/\__, /_/ /_/ /____/ __ _______ _______/ /____ ____ ___ / ___/ / / / ___/ __/ _ \/ __ `__ \ (__ ) /_/ (__ ) /_/ __/ / / / / / /____/\__, /____/\__/\___/_/ /_/ /_/ /____/

Hello, Design System
你好，设计系统
こんにちは、デザインシステム
안녕하세요, 디자인 시스템
Hola, Sistema de Diseño
Bonjour, Design System
Hallo, Designsystem
Olá, Sistema de Design
Привет, дизайн-система
مرحبًا، نظام التصميم

UI Text

io

The System

UI Basics

Enhancements

Io / UI Basics / VirtualList

VirtualList

VirtualList scrolls a million rows by rendering only the ones in view. Rows come from generated mock data, a static JSON, NDJSON or CSV file, or a paged range API, and search, sort and filtering run in a Web Worker so the page never blocks. Every colour resolves from the project tokens, so the list follows light and dark mode.

Data-driven34 controls1M rows · worker · paged API

Examples

Live specimens for every control the component exposes.

One million rows

Mock Rows is set to 1,000,000. The rows are generated once in a worker and the DOM only ever holds the visible rows plus overscan, so scrolling stays smooth at any size. The Framer canvas caps its preview at 500 rows; the published page scrolls the full million.

Loading rows…

0 rows

Selection

selection is none, single or multiple. Multiple takes Shift for a range and Cmd/Ctrl to toggle a row. Arrow keys, Page Up/Down, Home and End move focus, Enter or Space selects, and the footer counts the selection.

Loading rows…

0 rows

Columns and sorting

columns picks, orders and sizes the columns by key: label, width (0 is flexible) and align. Left empty, every column in the data appears. Click a header to sort ascending, again for descending, a third time to clear.

Loading rows…

0 rows

Filter

filterJSON narrows the rows before search and sort run. Nodes nest with and / or; leaf ops are eq, ne, in, gte, lte and contains. This one keeps Active rows with an amount of 5,000 or more. Invalid JSON is ignored and flagged in the footer.

Loading rows…

0 rows

Density and frame

cellPadding and rowHeight set the density from the theme padding scale; radius, border and shadow set the frame. autoHeight lets rows grow to fit wrapped text instead of truncating to one line.

Loading rows…

cellPadding XS · rowHeight 32 · search and footer off

Loading rows…

0 rows

cellPadding Large · rowHeight 48 · radius Large · shadow Normal

Data sources

source picks where rows come from. Static URL loads one file and parses it in a worker. Paged API speaks a small range protocol, below, so the server only ever sends the block being scrolled to. In both modes the canvas preview shows sample data.

Step	Request	Behaviour
Open a query	POST {apiBase}/query	Sends sort, search and filter; returns total, schema, queryId.
Fetch a block	GET {apiBase}/query/{queryId}/rows	start and count return one block of blockSize rows.
Small result	queryId null	Total fits inlineLimit: all rows inline, searched in memory.
Snapshot expired	HTTP 410	Reopens the same query and keeps the scroll position.
Static file	url + format	JSON, header-row arrays, NDJSON or CSV, parsed in a worker.
Authorization	Authorization header	Sent on every request when Auth is set. On 401 the token is resolved again and retried once.
Rate limited	HTTP 429 / 503	Backs off 2, 4, 8 … 30 s per block, honouring Retry-After. Two failures show Retry in the footer.

Step	Request	Behaviour
Open a query	POST {apiBase}/query	Sends sort, search and filter; returns total, schema, queryId.
Fetch a block	GET {apiBase}/query/{queryId}/rows	start and count return one block of blockSize rows.
Small result	queryId null	Total fits inlineLimit: all rows inline, searched in memory.
Snapshot expired	HTTP 410	Reopens the same query and keeps the scroll position.
Static file	url + format	JSON, header-row arrays, NDJSON or CSV, parsed in a worker.
Authorization	Authorization header	Sent on every request when Auth is set. On 401 the token is resolved again and retried once.
Rate limited	HTTP 429 / 503	Backs off 2, 4, 8 … 30 s per block, honouring Retry-After. Two failures show Retry in the footer.

Props

The 34 controls exposed on the instance panel. URL, API and Auth controls appear only when their source is selected.

Prop	Type	Behaviour
source	enum	Mock generates rows, Static URL loads one file, Paged API pages from a server.
mockCount	number	Rows generated in Mock mode, up to 2,000,000. Default 100,000; the canvas caps at 500.
url	string	Static URL mode: the file to load. Parsed in a Web Worker.
format	enum	Auto, JSON, NDJSON or CSV. Auto detects the format from the response.
apiBase	string	Paged API mode: the base URL for the query and row-block requests.
inlineLimit	number	Results up to this size load in one response and are searched in memory. Default 1,000.
blockSize	number	Rows per request in paged mode, 50 to 1,000, capped by the server's maxCount. Default 200.
sendCookies	boolean	Send or omit cookies on URL and API requests.
authSource	enum	None, Static Token, Browser Storage or Function. Adds an Authorization header to every data request; on a 401 the token is resolved again and the request retried once. Hidden in Mock mode.
authScheme	string	Prefixed to bare tokens. Default Bearer. Ignored when the token already contains a space; empty sends the raw value.
authToken	string	Static Token mode: the token itself. Baked into the published site and visible to every visitor, so use only read-only, revocable tokens.
authStorageKey	string	Browser Storage mode: the localStorage (then sessionStorage) key, read fresh on every request. JSON values use access_token, accessToken or token.
authFunction	string	Function mode: name of a window function returning a token or Promise<string>. Called with { refresh: true } after a 401. Default getAuthToken.
filterJSON	string	A filter tree applied before search and sort: and / or nodes; eq, ne, in, gte, lte, contains.
columns	array	Columns to show, in order: key, label, width (0 is flexible), align. Empty shows every column.
rowHeight	number	Exact row height, or the minimum and estimate when autoHeight is on. Default 40.
autoHeight	boolean	Wrap lets rows grow to fit wrapped text; Fixed keeps one truncated line per row.
overscan	number	Extra rows rendered above and below the viewport, 0 to 50. Default 8.
selection	enum	None, Single or Multiple. Multiple adds Shift ranges and Cmd/Ctrl toggles.
showSearch	boolean	Shows the search box. Search covers the string and date columns.
searchPlaceholder	string	Placeholder text in the search box. Default Search.
showFooter	boolean	Shows the footer: row count, selection count and status messages.
cellPadding	enum	XS, Small, Normal or Large, from the theme padding scale. Default Small.
radius	enum	None, Tiny, Small, Normal or Large corner radius. Default Normal.
border	enum	None, Small, Normal or Large outer border. Default Normal.
shadow	enum	None, Small, Normal or Large outer shadow. Default None.
background	color	Body fill. Empty follows the theme.
headerBackground	color	Header row fill. Empty follows the theme.
textColor	color	Cell text. Empty follows the theme.
secondaryTextColor	color	Header labels and footer text. Empty follows the theme.
dividerColor	color	Row, header and footer dividers. Empty follows the theme.
eventId	string	Sent as listId with every row click so listeners on the window event can tell lists apart.
onRowClick	event	Fires when a row is clicked, or activated with Enter or Space, with { listId, index, id, row, selected, selectedIds, trigger }. Also dispatched as the window event virtuallist:rowclick.
onLoadError	event	Fires when a data request fails. Also dispatched as the window event virtuallist:loaderror.

Prop	Type	Behaviour
source	enum	Mock generates rows, Static URL loads one file, Paged API pages from a server.
mockCount	number	Rows generated in Mock mode, up to 2,000,000. Default 100,000; the canvas caps at 500.
url	string	Static URL mode: the file to load. Parsed in a Web Worker.
format	enum	Auto, JSON, NDJSON or CSV. Auto detects the format from the response.
apiBase	string	Paged API mode: the base URL for the query and row-block requests.
inlineLimit	number	Results up to this size load in one response and are searched in memory. Default 1,000.
blockSize	number	Rows per request in paged mode, 50 to 1,000, capped by the server's maxCount. Default 200.
sendCookies	boolean	Send or omit cookies on URL and API requests.
authSource	enum	None, Static Token, Browser Storage or Function. Adds an Authorization header to every data request; on a 401 the token is resolved again and the request retried once. Hidden in Mock mode.
authScheme	string	Prefixed to bare tokens. Default Bearer. Ignored when the token already contains a space; empty sends the raw value.
authToken	string	Static Token mode: the token itself. Baked into the published site and visible to every visitor, so use only read-only, revocable tokens.
authStorageKey	string	Browser Storage mode: the localStorage (then sessionStorage) key, read fresh on every request. JSON values use access_token, accessToken or token.
authFunction	string	Function mode: name of a window function returning a token or Promise<string>. Called with { refresh: true } after a 401. Default getAuthToken.
filterJSON	string	A filter tree applied before search and sort: and / or nodes; eq, ne, in, gte, lte, contains.
columns	array	Columns to show, in order: key, label, width (0 is flexible), align. Empty shows every column.
rowHeight	number	Exact row height, or the minimum and estimate when autoHeight is on. Default 40.
autoHeight	boolean	Wrap lets rows grow to fit wrapped text; Fixed keeps one truncated line per row.
overscan	number	Extra rows rendered above and below the viewport, 0 to 50. Default 8.
selection	enum	None, Single or Multiple. Multiple adds Shift ranges and Cmd/Ctrl toggles.
showSearch	boolean	Shows the search box. Search covers the string and date columns.
searchPlaceholder	string	Placeholder text in the search box. Default Search.
showFooter	boolean	Shows the footer: row count, selection count and status messages.
cellPadding	enum	XS, Small, Normal or Large, from the theme padding scale. Default Small.
radius	enum	None, Tiny, Small, Normal or Large corner radius. Default Normal.
border	enum	None, Small, Normal or Large outer border. Default Normal.
shadow	enum	None, Small, Normal or Large outer shadow. Default None.
background	color	Body fill. Empty follows the theme.
headerBackground	color	Header row fill. Empty follows the theme.
textColor	color	Cell text. Empty follows the theme.
secondaryTextColor	color	Header labels and footer text. Empty follows the theme.
dividerColor	color	Row, header and footer dividers. Empty follows the theme.
eventId	string	Sent as listId with every row click so listeners on the window event can tell lists apart.
onRowClick	event	Fires when a row is clicked, or activated with Enter or Space, with { listId, index, id, row, selected, selectedIds, trigger }. Also dispatched as the window event virtuallist:rowclick.
onLoadError	event	Fires when a data request fails. Also dispatched as the window event virtuallist:loaderror.

Usage

Guidance carried over from the component definition.

Reach for VirtualList

Tens of thousands to millions of rows that scroll as one list.

The data is a static JSON, NDJSON or CSV file, or a server that pages by range.

Readers need instant search, column sort and a structured filter.

Rows need single or range selection with full keyboard support.

Reach for something else

A few hundred rows, or cells need badge, currency or percentage rendering: use TableX.

Cells need inline editing, grouping or tree rows.

The items are cards or media rather than tabular records.

Io — UI Basics

Every list above is a live VirtualList instance running on generated mock rows, not real data. Colour, type and radius resolve from the project theme tokens.