Maximum performance for extremely large grids.
Angular version 19.X.X.
npm i ng-virtual-grid
Template:
<ng-virtual-gridclass="grid regular" [items]="groupItems" [itemRenderer]="itemRenderer" [columnSize]="90" [rowSize]="38" [bufferSize]="0"></ng-virtual-grid><ng-template#itemRendererlet-data="data" let-measures="measures"> @if (data){<divclass="grid__item-container" [part]="data.isBorderStart ? 'border-start' : data.isBorderEnd ? 'border-end' : 'simple'" [class.border]="data.isBorder"><span>{{data.value}}</span></div> } </ng-template>Component:
import{Component}from'@angular/core';import{NgVirtualGridComponent,IVirtualGridCollection,IVirtualGridColumnCollection}from'ng-virtual-grid';constROWS=1000,COLUMNS=100;interfaceIRowData{}interfaceIColumnData{value: string;isBorderStart?: boolean;isBorderEnd?: boolean;}letnum=1;constgenerateNumber=()=>{constn=num;num++;returnString(n);}constGROUP_ITEMS: IVirtualGridCollection<IRowData,IColumnData>=[];letindex1=0;for(leti=0,l=ROWS;i<l;i++){constcolumns: IVirtualGridColumnCollection<IColumnData>=[];constrowId=index1;index1++;consttype=i===0||Math.random()>.895 ? 'group-header' : 'item';for(letj=0,l1=COLUMNS;j<l1;j++){index1++;constid=index1;columns.push({id: id,value: generateNumber()});}GROUP_ITEMS.push({id: rowId, columns });} @Component({selector: 'app-root',imports: [FormsModule,NgVirtualGridComponent],templateUrl: './app.component.html',styleUrl: './app.component.scss',})exportclassAppComponent{groupItems=GROUP_ITEMS;groupItemsStickyMap=GROUP_ITEMS_STICKY_MAP;}
Template:
<ng-virtual-gridclass="grid" [resizeRowsEnabled]="true" [resizeColumnsEnabled]="true" [items]="groupDynamicItems" [columnsSize]="groupDynamicColumnsSize" [rowsSize]="groupDynamicRowsSize" [itemRenderer]="itemRenderer" [minColumnSize]="32" [minRowSize]="32" [columnSize]="300" [rowSize]="32" [bufferSize]="0" [snap]="true" [cellConfigRowsMap]="groupDynamicItemsRowConfigMap" (onRowsSizeChanged)="onRowsSizeChangedHandler($event)" (onColumnsSizeChanged)="onColumnsSizeChangedHandler($event)"></ng-virtual-grid><ng-template#itemRendererlet-data="data" let-measures="measures"> @if (data){<divclass="grid__item-container" [part]="data.isBorderStart ? 'border-start' : data.isBorderEnd ? 'border-end' : 'simple'" [class.border]="data.isBorder"><span>{{data.value}}</span></div> } </ng-template>Component:
import{Component}from'@angular/core';import{NgVirtualGridComponent,IColumnsSize,IRowsSize,IVirtualGridCollection,IVirtualGridColumnCollection,IVirtualGridRowConfigMap,Id}from'ng-virtual-grid';import{PersistentStore}from'./utils';constDYNAMIC_ROWS=2000,DYNAMIC_COLUMNS=50;interfaceIRowData{}interfaceIColumnData{value: string;isBorderStart?: boolean;isBorderEnd?: boolean;}constCHARS=['a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v','w','x','y','z'];constgenerateLetter=()=>{returnCHARS[Math.round(Math.random()*CHARS.length)];}constgenerateWord=()=>{constlength=5+Math.floor(Math.random()*20),result=[];while(result.length<length){result.push(generateLetter());}return`${result.join('')}`;};constgenerateText=()=>{constlength=1+Math.floor(Math.random()*10),result=[];while(result.length<length){result.push(generateWord());}letfirstWord='';for(leti=0,l=result[0].length;i<l;i++){constletter=result[0].charAt(i);firstWord+=i===0 ? letter.toUpperCase() : letter;}result[0]=firstWord;return`${result.join(' ')}.`;};constGROUP_DYNAMIC_ITEMS: IVirtualGridCollection<IRowData,IColumnData>=[],GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP: IVirtualGridRowConfigMap={},GROUP_DYNAMIC_COLUMNS_SIZE_MAP: IColumnsSize={},GROUP_DYNAMIC_ROWS_SIZE_MAP: IRowsSize={};constGROUP_ITEMS: IVirtualGridCollection<IRowData,IColumnData>=[],GROUP_ITEMS_STICKY_MAP: IVirtualGridRowConfigMap={};letindex=0;for(leti=0,l=DYNAMIC_ROWS;i<l;i++){constcolumns: IVirtualGridColumnCollection<IColumnData>=[];constrowId=index;index++;if(i===0){GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP[rowId]={sticky: 1,};}elseif(i===l-20){GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP[rowId]={sticky: 1,};}elseif(i===l-1){GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP[rowId]={sticky: 2,};}for(letj=0,l1=DYNAMIC_COLUMNS;j<l1;j++){index++;constid=index;if(j===0||j===l1-1){GROUP_DYNAMIC_COLUMNS_SIZE_MAP[j]=36;}letvalue: string,isBorderStart: boolean=false,isBorderEnd: boolean=false;if((i===0&&j===0)||(i===0&&j===l1-1)){value='№';}elseif((i===l-1&&j===0)||(i===l-1&&j===l1-1)){value='';}elseif(i===0||i===l-1){value=String(j);}elseif(j===0||j===l1-1){value=String(i);}else{value=generateText();}columns.push({id: id, value, isBorderStart, isBorderEnd });}if(i===0||i===l-1){GROUP_DYNAMIC_ROWS_SIZE_MAP[rowId]=40;}GROUP_DYNAMIC_ITEMS.push({id: rowId, columns });}constgetDynamicRowsSize=()=>{constdefaultValue=GROUP_DYNAMIC_ROWS_SIZE_MAP,storedValue=PersistentStore.get('rows'),result={ ...defaultValue, ...storedValue||{}};returnresult;};constgetDynamicColumnsSize=()=>{constdefaultValue=GROUP_DYNAMIC_COLUMNS_SIZE_MAP,storedValue=PersistentStore.get('columns'),result={ ...defaultValue, ...storedValue||{}};returnresult;}; @Component({selector: 'app-root',imports: [FormsModule,NgVirtualGridComponent],templateUrl: './app.component.html',styleUrl: './app.component.scss',})exportclassAppComponent{readonlylogo=LOGO;groupDynamicItems=GROUP_DYNAMIC_ITEMS;groupDynamicItemsRowConfigMap=GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP;groupDynamicColumnsSize=getDynamicColumnsSize();groupDynamicRowsSize=getDynamicRowsSize();onRowsSizeChangedHandler(data: IRowsSize){letrowsData=PersistentStore.get('rows');if(rowsData){rowsData={ ...rowsData, ...data};PersistentStore.set('rows',rowsData);return;}PersistentStore.set('rows',data);}onColumnsSizeChangedHandler(data: IColumnsSize){letcoolumnsData=PersistentStore.get('columns');if(coolumnsData){coolumnsData={ ...coolumnsData, ...data};PersistentStore.set('columns',coolumnsData);return;}PersistentStore.set('columns',data);}}The example demonstrates the scrollTo method by passing it the element id.
Template:
<divclass="scroll-to__controls"><inputtype="number" class="scroll-to__input" [(ngModel)]="itemId" [required]="true" [min]="minId" [max]="maxId"><buttonclass="scroll-to__button" (click)="onButtonScrollToIdClickHandler($event)">Scroll</button></div><ng-virtual-gridclass="grid" [resizeRowsEnabled]="true" [resizeColumnsEnabled]="true" [items]="groupDynamicItems" [columnsSize]="groupDynamicColumnsSize" [rowsSize]="groupDynamicRowsSize" [itemRenderer]="itemRenderer" [minColumnSize]="32" [minRowSize]="32" [columnSize]="300" [rowSize]="32" [bufferSize]="0" [snap]="true" [cellConfigRowsMap]="groupDynamicItemsRowConfigMap" (onRowsSizeChanged)="onRowsSizeChangedHandler($event)" (onColumnsSizeChanged)="onColumnsSizeChangedHandler($event)"></ng-virtual-grid><ng-template#itemRendererlet-data="data" let-measures="measures"> @if (data){<divclass="grid__item-container" [part]="data.isBorderStart ? 'border-start' : data.isBorderEnd ? 'border-end' : 'simple'" [class.border]="data.isBorder"><span>{{data.value}}</span></div> } </ng-template>Component:
import{Component}from'@angular/core';import{NgVirtualGridComponent,IColumnsSize,IRowsSize,IVirtualGridCollection,IVirtualGridColumnCollection,IVirtualGridRowConfigMap,Id}from'ng-virtual-grid';import{PersistentStore}from'./utils';constDYNAMIC_ROWS=2000,DYNAMIC_COLUMNS=50;interfaceIRowData{}interfaceIColumnData{value: string;isBorderStart?: boolean;isBorderEnd?: boolean;}constCHARS=['a','b','c','d','e','f','g','h','i','j','k','l','m','n','o','p','q','r','s','t','u','v','w','x','y','z'];constgenerateLetter=()=>{returnCHARS[Math.round(Math.random()*CHARS.length)];}constgenerateWord=()=>{constlength=5+Math.floor(Math.random()*20),result=[];while(result.length<length){result.push(generateLetter());}return`${result.join('')}`;};constgenerateText=()=>{constlength=1+Math.floor(Math.random()*10),result=[];while(result.length<length){result.push(generateWord());}letfirstWord='';for(leti=0,l=result[0].length;i<l;i++){constletter=result[0].charAt(i);firstWord+=i===0 ? letter.toUpperCase() : letter;}result[0]=firstWord;return`${result.join(' ')}.`;};constGROUP_DYNAMIC_ITEMS: IVirtualGridCollection<IRowData,IColumnData>=[],GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP: IVirtualGridRowConfigMap={},GROUP_DYNAMIC_COLUMNS_SIZE_MAP: IColumnsSize={},GROUP_DYNAMIC_ROWS_SIZE_MAP: IRowsSize={};constGROUP_ITEMS: IVirtualGridCollection<IRowData,IColumnData>=[],GROUP_ITEMS_STICKY_MAP: IVirtualGridRowConfigMap={};letindex=0;for(leti=0,l=DYNAMIC_ROWS;i<l;i++){constcolumns: IVirtualGridColumnCollection<IColumnData>=[];constrowId=index;index++;if(i===0){GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP[rowId]={sticky: 1,};}elseif(i===l-20){GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP[rowId]={sticky: 1,};}elseif(i===l-1){GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP[rowId]={sticky: 2,};}for(letj=0,l1=DYNAMIC_COLUMNS;j<l1;j++){index++;constid=index;if(j===0||j===l1-1){GROUP_DYNAMIC_COLUMNS_SIZE_MAP[j]=36;}letvalue: string,isBorderStart: boolean=false,isBorderEnd: boolean=false;if((i===0&&j===0)||(i===0&&j===l1-1)){value='№';}elseif((i===l-1&&j===0)||(i===l-1&&j===l1-1)){value='';}elseif(i===0||i===l-1){value=String(j);}elseif(j===0||j===l1-1){value=String(i);}else{value=generateText();}columns.push({id: id, value, isBorderStart, isBorderEnd });}if(i===0||i===l-1){GROUP_DYNAMIC_ROWS_SIZE_MAP[rowId]=40;}GROUP_DYNAMIC_ITEMS.push({id: rowId, columns });}constgetDynamicRowsSize=()=>{constdefaultValue=GROUP_DYNAMIC_ROWS_SIZE_MAP,storedValue=PersistentStore.get('rows'),result={ ...defaultValue, ...storedValue||{}};returnresult;};constgetDynamicColumnsSize=()=>{constdefaultValue=GROUP_DYNAMIC_COLUMNS_SIZE_MAP,storedValue=PersistentStore.get('columns'),result={ ...defaultValue, ...storedValue||{}};returnresult;}; @Component({selector: 'app-root',imports: [FormsModule,NgVirtualGridComponent],templateUrl: './app.component.html',styleUrl: './app.component.scss',})exportclassAppComponent{readonlylogo=LOGO;protected_gridContainerRef=viewChild('grid',{read: NgVirtualGridComponent});groupDynamicItems=GROUP_DYNAMIC_ITEMS;groupDynamicItemsRowConfigMap=GROUP_DYNAMIC_ITEMS_ROW_CONFIG_MAP;groupDynamicColumnsSize=getDynamicColumnsSize();groupDynamicRowsSize=getDynamicRowsSize();private_minId: Id=this.groupDynamicItems.length>0 ? this.groupDynamicItems[0].id : 0;getminId(){returnthis._minId;};private_maxId: Id=this.groupDynamicItems.length>0 ? this.groupDynamicItems[this.groupDynamicItems.length-1].id : 0;getmaxId(){returnthis._maxId;};itemId: Id=this._minId;onButtonScrollToIdClickHandler=(e: Event)=>{constgrid=this._gridContainerRef();if(grid&&this.itemId!==undefined){grid.scrollTo(this.itemId,'instant');}}onRowsSizeChangedHandler(data: IRowsSize){letrowsData=PersistentStore.get('rows');if(rowsData){rowsData={ ...rowsData, ...data};PersistentStore.set('rows',rowsData);return;}PersistentStore.set('rows',data);}onColumnsSizeChangedHandler(data: IColumnsSize){letcoolumnsData=PersistentStore.get('columns');if(coolumnsData){coolumnsData={ ...coolumnsData, ...data};PersistentStore.set('columns',coolumnsData);return;}PersistentStore.set('columns',data);}}Grid items are encapsulated in shadowDOM, so to override default styles you need to use ::part access
- Customize a scroll area of grid
.grid::part(scroller){scroll-behavior: auto; /* custom scrollbar */&::-webkit-scrollbar{width:16px; height:16px} &::-webkit-scrollbar-track{background-color:#ffffff} &::-webkit-scrollbar-thumb{background-color:#d6dee1; border-radius:20px; border:6px solid transparent; background-clip: content-box; min-width:60px; min-height:60px} &::-webkit-scrollbar-thumb:hover{background-color:#a8bbbf} } .grid{border-radius:3px; box-shadow:1px2px8px4pxrgba(0,0,0,0.075); border:1px solid rgba(0,0,0,0.1)}- Set up the grid item canvas
.grid::part(grid){background-color:#ffffff}- Set up the grid item
.grid::part(grid-item){background-color: unset; // override default styles }- Set up the grid row odd item
.grid::part(item-row-odd){background-color:rgb(48,48,48)}- Set up the grid row even item
.grid::part(item-row-even){background-color:#363636} - Set up the grid row border item ```css .grid::part(item-row-border){background-color:#272727}Inputs
| Property | Type | Description |
|---|---|---|
| id | number | Readonly. Returns the unique identifier of the component. |
| items | IVirtualGridCollection | Collection of grid items. The collection of elements must be immutable. |
| columnSize | number? = 24 | Typical column size. Default value is 24. |
| rowSize | number? = 24 | Typical row size. Default value is 24. |
| minColumnSize | number? = 12 | Minimum column size. Default value is 12. |
| maxColumnSize | number? = 1200 | Maximum column size. Default value is 1200. |
| minRowSize | number? = 12 | Minimum row size. Default value is 12. |
| maxRowSize | number? = 1200 | Maximum row size. Default value is 1200. |
| bufferSize | number? = 2 | Number of elements outside the scope of visibility. Default value is 2. |
| maxBufferSize | number? = 2 | Maximum number of elements outside the scope of visibility. Default value is 2. If maxBufferSize is set to be greater than bufferSize, then adaptive buffer mode is enabled. The greater the scroll size, the more elements are allocated for rendering. |
| itemRenderer | TemplateRef | Rendering element template. |
| cellConfigRowsMap | IVirtualGridRowConfigMap? | Dictionary sticky and resizable by id of the grid row element. If the sticky value is not set or equal to 0, then a simple element is displayed, if the value is greater than 0, then the sticky position mode is enabled for the element. 1 - position start, 2 - position end. |
| cellConfigColumnsMap | IVirtualGridColumnConfigMap? | Dictionary resizable by id of the grid column element. |
| enabledBufferOptimization | boolean? = true | Experimental! Enables buffer optimization. Can only be used if items in the collection are not added or updated. |
Outputs
| Event | Type | Description |
|---|---|---|
| onItemClick | IRenderVirtualGridItem | undefined | Fires when an element is clicked. |
| onScroll | (IScrollEvent) => void | Fires when the grid has been scrolled. |
| onScrollEnd | (IScrollEvent) => void | Fires when the grid has completed scrolling. |
| onRowsSizeChanged | IRowsSize | Fires when the row size is changed. |
| onColumnsSizeChanged | IColumnsSize | Fires when the column size is changed. |
| onViewportChange | ISize | Fires when the viewport size is changed. |
Methods
| Method | Type | Description |
|---|---|---|
| scrollTo | (id: Id, behavior: ScrollBehavior = 'auto') => number | The method scrolls the list to the element with the given id and returns the value of the scrolled area. Behavior accepts the values "auto", "instant" and "smooth". |
| scrollToEnd | (behavior?: ScrollBehavior) => void | Scrolls the scroll area to the desired element with the specified ID. |
| getItemBounds | (id: Id, behavior?: ScrollBehavior) => void | Returns the bounds of an element with a given id |
To start a local development server, run:
ng serveOnce the server is running, open your browser and navigate to http://localhost:4200/. The application will automatically reload whenever you modify any of the source files.
MIT License
Copyright (c) 2025 djonnyx (Evgenii Grebennikov)
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.