{"id":13421870,"url":"https://github.com/inokawa/virtua","last_synced_at":"2025-05-12T13:17:23.305Z","repository":{"id":148848368,"uuid":"549650165","full_name":"inokawa/virtua","owner":"inokawa","description":"A zero-config, fast and small (~3kB) virtual list (and grid) component for React, Vue, Solid and Svelte.","archived":false,"fork":false,"pushed_at":"2025-05-03T12:20:14.000Z","size":106710,"stargazers_count":2755,"open_issues_count":74,"forks_count":69,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-05-12T13:16:04.259Z","etag":null,"topics":["headlessui","infinite-scroll","performance","react","react-component","scrolling","solid","svelte","tabular-data","virtual-list","virtual-scroll","virtualization","virtualized","vue","windowing"],"latest_commit_sha":null,"homepage":"https://inokawa.github.io/virtua/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/inokawa.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["inokawa"]}},"created_at":"2022-10-11T14:16:42.000Z","updated_at":"2025-05-12T08:36:58.000Z","dependencies_parsed_at":"2023-09-23T07:24:47.552Z","dependency_job_id":"ad62d18b-f1c5-4b0e-a8d6-83c758154fce","html_url":"https://github.com/inokawa/virtua","commit_stats":{"total_commits":1005,"total_committers":15,"mean_commits":67.0,"dds":0.09353233830845775,"last_synced_commit":"b9809ce806cd0bd473cb58622f807b868ec0b601"},"previous_names":[],"tags_count":141,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Fvirtua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Fvirtua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Fvirtua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/inokawa%2Fvirtua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/inokawa","download_url":"https://codeload.github.com/inokawa/virtua/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253745196,"owners_count":21957319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["headlessui","infinite-scroll","performance","react","react-component","scrolling","solid","svelte","tabular-data","virtual-list","virtual-scroll","virtualization","virtualized","vue","windowing"],"created_at":"2024-07-30T23:00:33.169Z","updated_at":"2025-05-12T13:17:23.291Z","avatar_url":"https://github.com/inokawa.png","language":"TypeScript","readme":"# virtua\n\n![npm](https://img.shields.io/npm/v/virtua) ![npm bundle size](https://img.shields.io/bundlephobia/minzip/virtua) ![npm](https://img.shields.io/npm/dw/virtua) [![Best of JS](https://img.shields.io/endpoint?url=https://bestofjs-serverless.now.sh/api/project-badge?fullName=inokawa%2Fvirtua%26since=daily)](https://bestofjs.org/projects/virtua) [![check](https://github.com/inokawa/virtua/actions/workflows/check.yml/badge.svg)](https://github.com/inokawa/virtua/actions/workflows/check.yml) [![demo](https://github.com/inokawa/virtua/actions/workflows/demo.yml/badge.svg)](https://github.com/inokawa/virtua/actions/workflows/demo.yml)\n\n\u003e A zero-config, fast and small (~3kB) virtual list (and grid) component for [React](https://github.com/facebook/react), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/) and [Svelte](https://svelte.dev/).\n\n![example](./example.gif)\n\nIf you want to check the difference with the alternatives right away, [see comparison section](#comparison).\n\n## Motivation\n\nThis project is a challenge to rethink virtualization. The goals are...\n\n- **Zero-config virtualization:** This library is designed to give the best performance without configuration. It also handles common hard things in the real world (dynamic size measurement, scroll position adjustment while reverse scrolling and imperative scrolling, iOS support, etc).\n- **Fast:** Natural virtual scrolling needs optimization in many aspects (eliminate frame drops by reducing CPU usage and GC, reduce [synchronous layout recalculation](https://gist.github.com/paulirish/5d52fb081b3570c81e3a), reduce visual jumps on repaint, optimize with CSS, optimize for frameworks, etc). We are trying to combine the best of them.\n- **Small:** Its bundle size should be small as much as possible to be friendly with modern web development. Currently each components are ~3kB gzipped and tree-shakeable. The total size for React is [~5kB gzipped](https://bundlephobia.com/package/virtua).\n- **Flexible:** Aiming to support many usecases - fixed size, dynamic size, horizontal scrolling, reverse scrolling, RTL, mobile, infinite scrolling, scroll restoration, DnD, keyboard navigation, sticky, placeholder and more. See [live demo](#demo).\n- **Framework agnostic:** [React](https://react.dev/), [Vue](https://vuejs.org/), [Solid](https://www.solidjs.com/) and [Svelte](https://svelte.dev/) are supported. We could support other frameworks in the future.\n\n## Demo\n\nhttps://inokawa.github.io/virtua/\n\n## Install\n\n```sh\nnpm install virtua\n```\n\nIf you use this lib in [legacy browsers which does not have ResizeObserver](https://caniuse.com/?search=resizeobserver), you should use [polyfill](https://github.com/juggle/resize-observer#switching-between-native-and-polyfilled-versions).\n\n## Getting started\n\n### React\n\n`react \u003e= 16.14` is required.\n\nIf you use ESM and webpack 5, use react \u003e= 18 to avoid [Can't resolve `react/jsx-runtime` error](https://github.com/facebook/react/issues/20235).\n\n#### Vertical scroll\n\n```tsx\nimport { VList } from \"virtua\";\n\nexport const App = () =\u003e {\n return (\n \u003cVList style={{ height: 800 }}\u003e\n {Array.from({ length: 1000 }).map((_, i) =\u003e (\n \u003cdiv\n key={i}\n style={{\n height: Math.floor(Math.random() * 10) * 10 + 10,\n borderBottom: \"solid 1px gray\",\n background: \"white\",\n }}\n \u003e\n {i}\n \u003c/div\u003e\n ))}\n \u003c/VList\u003e\n );\n};\n```\n\n#### Horizontal scroll\n\n```tsx\nimport { VList } from \"virtua\";\n\nexport const App = () =\u003e {\n return (\n \u003cVList style={{ height: 400 }} horizontal\u003e\n {Array.from({ length: 1000 }).map((_, i) =\u003e (\n \u003cdiv\n key={i}\n style={{\n width: Math.floor(Math.random() * 10) * 10 + 10,\n borderRight: \"solid 1px gray\",\n background: \"white\",\n }}\n \u003e\n {i}\n \u003c/div\u003e\n ))}\n \u003c/VList\u003e\n );\n};\n```\n\n#### Customization\n\n`VList` is a recommended solution which works like a drop-in replacement of simple list built with scrollable `div` (or removed [virtual-scroller element](https://github.com/WICG/virtual-scroller)). For more complicated styling or markup, use `Virtualizer`.\n\n```tsx\nimport { Virtualizer } from \"virtua\";\n\nexport const App = () =\u003e {\n return (\n \u003cdiv style={{ overflowY: \"auto\", height: 800 }}\u003e\n \u003cdiv style={{ height: 40 }}\u003eheader\u003c/div\u003e\n \u003cVirtualizer startMargin={40}\u003e\n {Array.from({ length: 1000 }).map((_, i) =\u003e (\n \u003cdiv\n key={i}\n style={{\n height: Math.floor(Math.random() * 10) * 10 + 10,\n borderBottom: \"solid 1px gray\",\n background: \"white\",\n }}\n \u003e\n {i}\n \u003c/div\u003e\n ))}\n \u003c/Virtualizer\u003e\n \u003c/div\u003e\n );\n};\n```\n\n#### Window scroll\n\n```tsx\nimport { WindowVirtualizer } from \"virtua\";\n\nexport const App = () =\u003e {\n return (\n \u003cdiv style={{ padding: 200 }}\u003e\n \u003cWindowVirtualizer\u003e\n {Array.from({ length: 1000 }).map((_, i) =\u003e (\n \u003cdiv\n key={i}\n style={{\n height: Math.floor(Math.random() * 10) * 10 + 10,\n borderBottom: \"solid 1px gray\",\n background: \"white\",\n }}\n \u003e\n {i}\n \u003c/div\u003e\n ))}\n \u003c/WindowVirtualizer\u003e\n \u003c/div\u003e\n );\n};\n```\n\n#### Vertical and horizontal scroll\n\n```tsx\nimport { experimental_VGrid as VGrid } from \"virtua\";\n\nexport const App = () =\u003e {\n return (\n \u003cVGrid style={{ height: 800 }} row={1000} col={500}\u003e\n {({ rowIndex, colIndex }) =\u003e (\n \u003cdiv\n style={{\n width: ((colIndex % 3) + 1) * 100,\n border: \"solid 1px gray\",\n background: \"white\",\n }}\n \u003e\n {rowIndex} / {colIndex}\n \u003c/div\u003e\n )}\n \u003c/VGrid\u003e\n );\n};\n```\n\n#### React Server Components (RSC) support\n\nThis library is marked as a Client Component. You can render RSC as children of `VList`, `Virtualizer` or `WindowVirtualizer`.\n\n```tsx\n// page.tsx in App Router of Next.js\n\nexport default async () =\u003e {\n const articles = await fetchArticles();\n return (\n \u003cdiv\u003e\n \u003cdiv\u003eThis is Server Component\u003c/div\u003e\n \u003cVList style={{ height: 300 }}\u003e\n {articles.map((a) =\u003e (\n \u003cdiv key={a.id} style={{ border: \"solid 1px gray\", height: 80 }}\u003e\n {a.content}\n \u003c/div\u003e\n ))}\n \u003c/VList\u003e\n \u003c/div\u003e\n );\n};\n```\n\n### Vue\n\n`vue \u003e= 3.2` is required.\n\n```vue\n\u003cscript setup\u003e\nimport { VList } from \"virtua/vue\";\n\nconst sizes = [20, 40, 180, 77];\nconst data = Array.from({ length: 1000 }).map((_, i) =\u003e sizes[i % 4]);\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n \u003cVList :data=\"data\" :style=\"{ height: '800px' }\" #default=\"{ item, index }\"\u003e\n \u003cdiv\n :key=\"index\"\n :style=\"{\n height: item + 'px',\n background: 'white',\n borderBottom: 'solid 1px #ccc',\n }\"\n \u003e\n {{ index }}\n \u003c/div\u003e\n \u003c/VList\u003e\n\u003c/template\u003e\n```\n\n### Solid\n\n`solid-js \u003e= 1.0` is required.\n\n```tsx\nimport { VList } from \"virtua/solid\";\n\nexport const App = () =\u003e {\n const sizes = [20, 40, 80, 77];\n const data = Array.from({ length: 1000 }).map((_, i) =\u003e sizes[i % 4]);\n\n return (\n \u003cVList data={data} style={{ height: \"800px\" }}\u003e\n {(d, i) =\u003e (\n \u003cdiv\n style={{\n height: d + \"px\",\n \"border-bottom\": \"solid 1px #ccc\",\n background: \"#fff\",\n }}\n \u003e\n {i()}\n \u003c/div\u003e\n )}\n \u003c/VList\u003e\n );\n};\n```\n\n### Svelte\n\n`svelte \u003e= 5.0` is required.\n\n```svelte\n\u003cscript lang=\"ts\"\u003e\n import { VList } from \"virtua/svelte\";\n\n const sizes = [20, 40, 180, 77];\n\n const data = Array.from({ length: 1000 }).map((_, i) =\u003e sizes[i % 4] );\n\u003c/script\u003e\n\n\u003cVList {data} style=\"height: 100vh;\" getKey={(_, i) =\u003e i}\u003e\n {#snippet children(item, index)}\n \u003cdiv\n style=\"\n height: {item}px;\n background: white;\n border-bottom: solid 1px #ccc;\n \"\n \u003e\n {index}\n \u003c/div\u003e\n {/snippet}\n\u003c/VList\u003e\n```\n\n### Other bindings\n\n- [vanilla-virtua](https://github.com/aabccd021/vanilla-virtua): virtua for vanilla js\n\n## Documentation\n\n- [API reference](./docs/API.md)\n- [Storybook examples](./stories) for more usages\n\n### FAQs\n\n#### Is there any way to improve performance further?\n\nIn complex usage, especially if you re-render frequently the parent of virtual scroller or the children are tons of items, children element creation can be a performance bottle neck. That's because creating React elements is fast enough but not free and new React element instances break some of memoization inside virtual scroller.\n\nOne solution is memoization with [`useMemo`](https://react.dev/reference/react/useMemo). You can use it to reduce computation and keep the elements' instance the same. And if you want to pass state from parent to the items, using [`context`](https://react.dev/learn/passing-data-deeply-with-context) instead of props may be better because it doesn't break the memoization.\n\n```tsx\nconst elements = useMemo(\n () =\u003e tooLongArray.map((d) =\u003e \u003cComponent key={d.id} {...d} /\u003e),\n [tooLongArray]\n);\nconst [position, setPosition] = useState(0);\nreturn (\n \u003cdiv\u003e\n \u003cdiv\u003eposition: {position}\u003c/div\u003e\n \u003cVList onScroll={(offset) =\u003e setPosition(offset)}\u003e{elements}\u003c/VList\u003e\n \u003c/div\u003e\n);\n```\n\nThe other solution is using [`render prop`](https://legacy.reactjs.org/docs/render-props.html) as children to create elements lazily. It will effectively reduce cost on start up when you render many items (\u003e1000). An important point is that newly created elements from `render prop` will disable [optimization possible with cached element instances](https://github.com/facebook/react/issues/8669#issuecomment-270032204). We recommend using [`memo`](https://react.dev/reference/react/memo) to reduce calling render function of your item components during scrolling.\n\n```tsx\nconst Component = memo(HeavyItem);\n\n\u003cVList count={items.length}\u003e\n {(i) =\u003e {\n const item = items[i];\n return \u003cComponent key={item.id} data={item} /\u003e;\n }}\n\u003c/VList\u003e;\n```\n\nDecreasing `overscan` prop may also improve perf in case that components are large and heavy.\n\nVirtua try to suppress glitch caused by resize as much as possible, but it will also require additional work. If your item contains something resized often, such as lazy loaded image, we recommend to set height or min-height to it if possible.\n\n#### What is `ResizeObserver loop completed with undelivered notifications.` error?\n\nIt may be dispatched by ResizeObserver in this lib [as described in spec](https://www.w3.org/TR/resize-observer/#deliver-resize-error), and [this is a common problem with ResizeObserver](https://github.com/w3c/csswg-drafts/issues/5488). If it bothers you,\n[you can safely ignore it](https://github.com/DevExpress/testcafe/issues/4857#issuecomment-598775956).\n\nEspecially for `webpack-dev-server`, [you can filter out the specific error with `devServer.client.overlay.runtimeErrors` option](https://webpack.js.org/configuration/dev-server/#overlay).\n\n#### Why my items are squashed(or rendered inconsistently) on resize/add/remove?\n\nMaybe you forgot to pass `key` prop to each items, or the keys are not unique. Item sizes are stored per key.\n\nAnd do not use index of items as `key`, especially when you want to toggle `shift` prop to `true`. Prepending will increment every indexes of items and that will cause unexpected behavior.\n\n#### Why `VListHandle.viewportSize` is 0 on mount?\n\n`viewportSize` will be calculated by ResizeObserver so it's 0 until the first measurement.\n\n#### What is `Cannot find module 'virtua/vue(solid|svelte)' or its corresponding type declarations` error?\n\nThis package uses [exports of package.json](https://nodejs.org/api/packages.html#package-entry-points) for entry point of Vue/Solid/Svelte adapter. This field can't be resolved in TypeScript with `moduleResolution: node`. Try `moduleResolution: bundler` or `moduleResolution: nodenext` instead.\n\n## Comparison\n\n### Features\n\n| | [virtua](https://github.com/inokawa/virtua) | [react-virtuoso](https://github.com/petyosi/react-virtuoso) | [react-window](https://github.com/bvaughn/react-window) | [react-virtualized](https://github.com/bvaughn/react-virtualized) | [@tanstack/react-virtual](https://github.com/TanStack/virtual) | [react-tiny-virtual-list](https://github.com/clauderic/react-tiny-virtual-list) | [react-cool-virtual](https://github.com/wellyshen/react-cool-virtual) |\n| :------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------- |\n| Bundle size | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/virtua)](https://bundlephobia.com/package/virtua) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-virtuoso)](https://bundlephobia.com/package/react-virtuoso) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-window)](https://bundlephobia.com/package/react-window) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-virtualized)](https://bundlephobia.com/package/react-virtualized) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/@tanstack/react-virtual)](https://bundlephobia.com/package/@tanstack/react-virtual) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-tiny-virtual-list)](https://bundlephobia.com/package/react-tiny-virtual-list) | [![npm bundle size](https://img.shields.io/bundlephobia/minzip/react-cool-virtual)](https://bundlephobia.com/package/react-cool-virtual) |\n| Vertical scroll | ✅ | ✅ | ✅ | ✅ | 🟠 (needs customization) | ✅ | 🟠 (needs customization) |\n| Horizontal scroll | ✅ | ✅ | ✅ ([may be dropped in v2](https://github.com/bvaughn/react-window/issues/302)) | ✅ | 🟠 (needs customization) | ✅ | 🟠 (needs customization) |\n| Horizontal scroll in RTL direction | ✅ | ❌ | ✅ ([may be dropped in v2](https://github.com/bvaughn/react-window/issues/302)) | ❌ | ❌ | ❌ | ❌ |\n| Grid (Virtualization for two dimension) | 🟠 (experimental_VGrid) | ❌ | ✅ (FixedSizeGrid / VariableSizeGrid) | ✅ ([Grid](https://github.com/bvaughn/react-virtualized/blob/master/docs/Grid.md)) | 🟠 (needs customization) | ❌ | 🟠 (needs customization) |\n| Table | 🟠 (needs customization) | ✅ (TableVirtuoso) | 🟠 (needs customization) | 🟠 ([Table](https://github.com/bvaughn/react-virtualized/blob/master/docs/Table.md) but it's built with div) | 🟠 (needs customization) | ❌ | 🟠 (needs customization) |\n| Window scroller | ✅ (WindowVirtualizer) | ✅ | ❌ | ✅ ([WindowScroller](https://github.com/bvaughn/react-virtualized/blob/master/docs/WindowScroller.md)) | ✅ (useWindowVirtualizer) | ❌ | ❌ |\n| Dynamic list size | ✅ | ✅ | 🟠 (needs [AutoSizer](https://github.com/bvaughn/react-virtualized/blob/master/docs/AutoSizer.md)) | 🟠 (needs [AutoSizer](https://github.com/bvaughn/react-virtualized/blob/master/docs/AutoSizer.md)) | ✅ | ❌ | ✅ |\n| Dynamic item size | ✅ | ✅ | 🟠 (needs additional codes and has wrong destination when scrolling to item imperatively) | 🟠 (needs [CellMeasurer](https://github.com/bvaughn/react-virtualized/blob/master/docs/CellMeasurer.md) and has wrong destination when scrolling to item imperatively) | 🟠 (has wrong destination when scrolling to item imperatively) | ❌ | 🟠 (has wrong destination when scrolling to item imperatively) |\n| Reverse scroll | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Reverse scroll in iOS Safari | 🟠 ([user must release scroll](https://github.com/inokawa/virtua/issues/473)) | 🟠 ([has glitch with unknown sized items](https://github.com/petyosi/react-virtuoso/issues/945)) | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Infinite scroll | ✅ | ✅ | 🟠 (needs [react-window-infinite-loader](https://github.com/bvaughn/react-window-infinite-loader)) | 🟠 (needs [InfiniteLoader](https://github.com/bvaughn/react-virtualized/blob/master/docs/InfiniteLoader.md)) | ✅ | ❌ | ✅ |\n| Reverse (bi-directional) infinite scroll | ✅ | ✅ | ❌ | ❌ | ❌ | ❌ | 🟠 (has startItem method but its scroll position can be inaccurate) |\n| Scroll restoration | ✅ | ✅ (getState) | ❌ | ❌ | ❌ | ❌ | ❌ |\n| Smooth scroll | ✅ | ✅ | ❌ | ❌ | ✅ | ❌ | ✅ |\n| SSR support | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ | ✅ |\n| Render React Server Components (RSC) as children | ✅ | ❌ | ❌ | ❌ | 🟠(needs customization) | ❌ | 🟠 (needs customization) |\n| Display exceeding [browser's max element size](https://stackoverflow.com/questions/10882769/do-the-browsers-have-a-maximum-height-for-the-body-document) limit | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ | ❌ |\n\n- ✅ - Built-in supported\n- 🟠 - Supported but partial, limited or requires some user custom code\n- ❌ - Not officially supported\n\n### Benchmark\n\nWIP\n\n## Contribute\n\nAll contributions are welcome.\nIf you find a problem, feel free to create an [issue](https://github.com/inokawa/virtua/issues) or a [PR](https://github.com/inokawa/virtua/pulls). If you have a question, ask in [discussions](https://github.com/inokawa/virtua/discussions).\n\n### Making a Pull Request\n\n1. Fork this repo.\n2. Run `npm install`.\n3. Commit your fix.\n4. Make a PR and confirm all the CI checks passed.\n","funding_links":["https://github.com/sponsors/inokawa"],"categories":["UI Components","TypeScript","Projects using `@faker-js/faker`","📦 Components \u0026 Libraries","Packages","🧰 React Toolkit","Libraries","Components \u0026 Libraries"],"sub_categories":["Infinite Scroll","UI Components","Virtualization"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finokawa%2Fvirtua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finokawa%2Fvirtua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finokawa%2Fvirtua/lists"}