{"id":13808770,"url":"https://github.com/lVlyke/lithium-ngx-virtual-scroll","last_synced_at":"2025-05-14T03:31:29.371Z","repository":{"id":33659196,"uuid":"156328528","full_name":"lVlyke/lithium-ngx-virtual-scroll","owner":"lVlyke","description":"A fast and lightweight virtual scrolling solution for Angular that supports single column lists, grid lists and view caching.","archived":false,"fork":false,"pushed_at":"2024-09-24T02:16:03.000Z","size":445,"stargazers_count":23,"open_issues_count":4,"forks_count":4,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-10-04T07:21:51.963Z","etag":null,"topics":["angular","grid","lithium-angular","ngx","rxjs","scroll","typescript","virtual","virtual-scroll"],"latest_commit_sha":null,"homepage":"","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/lVlyke.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}},"created_at":"2018-11-06T05:03:04.000Z","updated_at":"2024-09-18T20:20:34.000Z","dependencies_parsed_at":"2024-07-15T18:46:59.562Z","dependency_job_id":null,"html_url":"https://github.com/lVlyke/lithium-ngx-virtual-scroll","commit_stats":{"total_commits":34,"total_committers":2,"mean_commits":17.0,"dds":"0.38235294117647056","last_synced_commit":"4d8a19ba672a7471cdb6d06aa9714dd58c41f21c"},"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lVlyke%2Flithium-ngx-virtual-scroll","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lVlyke%2Flithium-ngx-virtual-scroll/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lVlyke%2Flithium-ngx-virtual-scroll/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lVlyke%2Flithium-ngx-virtual-scroll/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lVlyke","download_url":"https://codeload.github.com/lVlyke/lithium-ngx-virtual-scroll/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225273268,"owners_count":17448076,"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":["angular","grid","lithium-angular","ngx","rxjs","scroll","typescript","virtual","virtual-scroll"],"created_at":"2024-08-04T01:01:51.492Z","updated_at":"2025-05-14T03:31:29.364Z","avatar_url":"https://github.com/lVlyke.png","language":"TypeScript","funding_links":[],"categories":["Third Party Components"],"sub_categories":["Scroll"],"readme":"# @lithiumjs/ngx-virtual-scroll\n\nA fast and lightweight virtual scrolling solution for Angular that supports single column lists, grid lists and view caching.\n\n## [Live demo](https://lvlyke.github.io/lithium-ngx-virtual-scroll-demo/) ([Code](https://github.com/lVlyke/lithium-ngx-virtual-scroll-demo))\n\n\u003e * [**Installing**](#installing)\n\u003e * [**Usage guide**](#usage-guide)\n\u003e * [**Troubleshooting**](#troubleshooting)\n\u003e * [**API reference**](#api-reference)\n\u003e * [**Other information**](#other-information)\n\n# Installing\n\n@lithiumjs/ngx-virtual-scroll requires [@lithiumjs/angular](https://github.com/lVlyke/lithium-angular). Both can be installed from npm:\n\n```bash\nnpm install @lithiumjs/angular @lithiumjs/ngx-virtual-scroll\n```\n\n# Usage guide\n\nImport `NgxVirtualScrollModule`. Use the `li-virtual-scroll` component to declare a list with virtual scrolling:\n\n```html\n\u003cli-virtual-scroll [items]=\"items\"\u003e\n    \u003c!-- liVirtualItem defines a list item element for each item --\u003e\n    \u003cdiv *liVirtualItem=\"let item\"\u003e\n        {{ item.name }}\n    \u003c/div\u003e\n\u003c/li-virtual-scroll\u003e\n```\n\n**Note:** The `li-virtual-scroll` element is a scroll container and needs to have a defined maximum size to ensure scrolling occurs.\n\n## Item element size\n\nThe size of the list item elements can either be explicitly passed in, or calculated automatically. Width is only required for grid lists.\n\n\u003e [!IMPORTANT]\n\u003e All item elements in the list must be the same size. For best results, make sure that the elements have a constant size that does not change. If the element size is not constant and changes based on the number of elements in the container (i.e. flexbox), then the item size **must** be declared explicitly.\n\n### Automatic item size\n\nIf `itemWidth` or `itemHeight` are not explicitly passed, they will be automatically calculated by rendering the first item in the list and recording its size. This method only works for list items that have a constant size.\n\n### Explicit item size\n\nUse the `itemWidth` and `itemHeight` inputs to explicitly declare the width/height (in pixels) of the list item elements:\n\n```html\n\u003cli-virtual-scroll [items]=\"items\" [itemWidth]=\"128\" [itemHeight]=\"128\"\u003e\n    \u003cdiv *liVirtualItem=\"let item\"\u003e\n        {{ item.name }}\n    \u003c/div\u003e\n\u003c/li-virtual-scroll\u003e\n```\n\n\u003e [!NOTE]\n\u003e Include the element's margins as part of the width/height.\n\n## Grid lists (multiple items per row)\n\nIf the list being rendered is a grid list with multiple items per row, make sure to set `gridList` to `true`:\n\n```html\n\u003cli-virtual-scroll [items]=\"items\" [gridList]=\"true\"\u003e\n    \u003cdiv *liVirtualItem=\"let item\"\u003e\n        {{ item.name }}\n    \u003c/div\u003e\n\u003c/li-virtual-scroll\u003e\n```\n\n## Asynchronous view rendering\n\nAsynchronous view rendering can be used to improve scrolling responsiveness for items with complex views. When enabled, a placeholder element will be temporarily be shown while the item is rendered asynchronously. The placeholder element can be customized using the `liVirtualPlaceholder` directive:\n\n```html\n\u003cli-virtual-scroll [items]=\"items\" [asyncRendering]=\"true\"\u003e\n     \u003c!-- Items contain complex components: --\u003e\n    \u003cdiv *liVirtualItem=\"let item\"\u003e\n        {{ item.name }}\n\n        \u003capp-complex-component\u003e...\u003c/app-complex-component\u003e\n    \u003c/div\u003e\n\n    \u003c!-- Placeholder only prints the item name: --\u003e\n    \u003cdiv *liVirtualPlaceholder=\"let item\"\u003e\n        {{ item.name }}\n    \u003c/div\u003e\n\u003c/li-virtual-scroll\u003e\n```\n\nNote that the placeholder should be lightweight so that it can be rendered quickly.\n\n## View caching\n\nView caching can be enabled to improve scrolling performance by caching views that are not being rendered for later re-use. View caching can be toggled on or off, or enabled with a maximum cache size (recommended for very large lists or complex views, as these could cause high memory usage):\n\n```html\n\u003c!-- Up to 256 views will be cached --\u003e\n\u003cli-virtual-scroll [items]=\"items\" [viewCache]=\"256\"\u003e\n    \u003cdiv *liVirtualItem=\"let item\"\u003e\n        {{ item.name }}\n    \u003c/div\u003e\n\u003c/li-virtual-scroll\u003e\n```\n\n## Scroll debounce\n\nThe scroll debounce controls how often the virtual scroll should respond to scroll position changes. The default is 50 milliseconds.\n\n```html\n\u003c!-- Virtual scroll will render on scroll changes every 100ms --\u003e\n\u003cli-virtual-scroll [items]=\"items\" [scrollDebounceMs]=\"100\"\u003e\n    \u003cdiv *liVirtualItem=\"let item\"\u003e\n        {{ item.name }}\n    \u003c/div\u003e\n\u003c/li-virtual-scroll\u003e\n```\n\n## Scroll buffer\n\nIncreasing the scroll buffer length will render more items outside of the viewport, which can reduce view pop-in when scrolling quickly. The buffer length is expressed in multiples of the list container's client height:\n\n```html\n\u003cli-virtual-scroll [items]=\"items\" [bufferLength]=\"3\"\u003e\n    \u003cdiv *liVirtualItem=\"let item\"\u003e\n        {{ item.name }}\n    \u003c/div\u003e\n\u003c/li-virtual-scroll\u003e\n```\n\n## Providing a custom virtual scroll strategy\n\nThe default virtual scroll strategy can be overriden by providing a custom `VirtualScrollStrategy` service implementation using the `LI_VIRTUAL_SCROLL_STRATEGY` injection token:\n\n```ts\n@NgModule({\n    providers: [\n        {\n            provide: LI_VIRTUAL_SCROLL_STRATEGY,\n            useClass: AppFooVirtualScrollStrategy\n        }\n    ]\n})\nexport class AppFooModule {}\n```\n\nThe default virtual scroll strategy can also be overriden using `NgxVirtualScrollModule.withOptions`:\n\n```ts\n@NgModule({\n    imports: [\n        NgxVirtualScrollModule.withOptions({\n            scrollStrategy: AppFooVirtualScrollStrategy\n        })\n    ]\n})\nexport class AppModule {}\n```\n\n# Troubleshooting\n\n## All items are rendered\n\nThis can happen when your list element has an unlimited height. The `li-virtual-scroll` component is a scroll container that needs a maximum height for virtual scrolling to work. You must apply a maximum height to the list element for virtual scrolling to work.\n\n## Only one item is rendered\n\nThis usually happens when your list item elements do not have a constant size and you have not explicitly declared `itemWidth`/`itemHeight`.\n\nIf your list container uses a layout that dynamically resizes elements (i.e. flexbox), you must ensure that the items have a constant size for the automatic width/height calculation to work correctly. The easiest way to achieve this is to add a fixed width/height in CSS. If this is not possible, you must instead explicitly declare the item size using the `itemWidth`/`itemHeight` inputs. See [this section](#item-element-size) for more information.\n\n## Not enough items are rendered\n\nThis can happen when incorrect `itemWidth`/`itemHeight` values are given. Make sure that you have calculated the size of your elements correctly (this should also include margins). See [this section](#explicit-item-size) for more information.\n\n# API reference\n\n## `VirtualScroll` (`li-virtual-scroll`)\n\nComponent used to create a virtual scrolling container.\n### **Inputs**\n\n* **`items`** - The list of items to render.\n* **`asyncRendering`** - (Optional) Whether or not to enable asynchronous rendering of views, which loads in placeholder elements while rendering items. Defaults to `false`.\n* **`bufferLength`** - (Optional) How much extra list content should be rendered, measured in multiples of the list container's client height. This helps improve scrolling responsiveness for fast scrolling. Defaults to `1`.\n* **`eventCapture`** - (Optional) Whether or not to use event capture mode for capturing scroll events from `scrollContainer`. Defaults to `false`.\n* **`gridList`** - (Optional) Whether or not the list is a grid list with multiple items per row. Defaults to `false`.\n* **`itemWidth`** - (Optional) The width of each item being rendered, in pixels. Calculated automatically based on the width of the first item if not given.\n* **`itemHeight`** - (Optional) The height of each item being rendered, in pixels. Calculated automatically based on the height of the first item if not given.\n* **`scrollDebounceMs`** - (Optional) How often to respond to scroll position changes, in milliseconds. Defaults to `50`.\n* **`trackBy`** - (Optional) A [`TrackByFunction`](https://angular.io/api/core/TrackByFunction) used to compute the identity of items. Defaults to a function returning the item reference.\n* **`viewCache`** - (Optional) Whether views can be cached. Can be a boolean or a number representing the maximum number of views to cache at a given time. Defaults to `false`.\n\n## `VirtualItem` (`[liVirtualItem]`)\n\nStructural directive used to render items inside a `li-virtual-scroll` component.\n\n## `VirtualPlaceholder` (`[liVirtualPlaceholder]`)\n\nStructural directive used to render placeholder elements inside a `li-virtual-scroll` component.\n\n## `NgxVirtualScrollModule`\n\nThe Angular module for this library.\n### `NgxVirtualScrollModule.Options`\n\nThe options to configure the module with.\n\n```ts\nexport interface Options {\n    scrollStrategy?: Type\u003cVirtualScrollStrategy\u003cunknown\u003e\u003e;\n}\n```\n\n* `scrollStrategy` - The custom `VirtualScrollStrategy` service implementation to use.\n\n### `NgxVirtualScrollModule.withOptions`\n\nAllows configuration of the module with custom options.\n\n```ts\nexport class NgxVirtualScrollModule {\n\n    public static withOptions(\n        options: NgxVirtualScrollModule.Options\n    ): ModuleWithProviders\u003cNgxVirtualScrollModule\u003e;\n}\n```\n\n* `options` - The options to configure the module with.\n\n## `VirtualScrollStrategy`\n\nInterface for defining a custom virtual scroll strategy.\n\n```ts\nexport interface VirtualScrollStrategy\u003cT\u003e {\n\n    destroyViewRef(\n        scrollState: VirtualScrollState\u003cT\u003e,\n        viewRef: EmbeddedViewRef\u003cVirtualItem.ViewContext\u003cT\u003e\u003e\n    ): void;\n\n    destroyView(\n        scrollState: VirtualScrollState\u003cT\u003e,\n        view: VirtualScrollState.ViewInfo\u003cT\u003e\n    ): void;\n\n    cacheView(\n        scrollState: VirtualScrollState\u003cT\u003e,\n        view: VirtualScrollState.ViewInfo\u003cT\u003e\n    ): void;\n\n    renderViewForItem(\n        scrollState: VirtualScrollState\u003cT\u003e,\n        item: T,\n        globalIndex: number,\n        deferViewCreation?: boolean\n    ): Observable\u003cVirtualScrollState.ViewInfo\u003cT\u003e\u003e;\n\n    unrenderView(\n        scrollState: VirtualScrollState\u003cT\u003e,\n        view: VirtualScrollState.ViewInfo\u003cT\u003e\n    ): void;\n\n    purgeViewCache(scrollState: VirtualScrollState\u003cT\u003e): void;\n}\n```\n\n## `DefaultVirtualScrollStrategy`\n\nThe default `VirtualScrollStrategy` service implementation.\n\n# Other information\n\n* [Lithium for Angular](https://github.com/lVlyke/lithium-angular)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FlVlyke%2Flithium-ngx-virtual-scroll","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FlVlyke%2Flithium-ngx-virtual-scroll","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FlVlyke%2Flithium-ngx-virtual-scroll/lists"}