ngx-datatable Documentation

A feature-rich yet lightweight data-table crafted for Angular

RAW Doc

Technical Documentation: swimlane/ngx-datatable

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`)

ngx-datatable





ngx-datatable is an Angular component for presenting large and complex data. It has all the features you would expect from any other table but in a light package with no external dependencies. The table was designed to be extremely flexible and light; it doesn't make any assumptions about your data or how you: filter, sort or page it.

Check out the documentation & demos for more information!

See the changelog for recent changes.

Features

  • Handle large data sets ( Virtual DOM )
  • Expressive Header and Cell Templates
  • Horizontal & Vertical Scrolling
  • Column Reordering & Resizing
  • Client/Server side Pagination & Sorting
  • Intelligent Column Width Algorithms ( Force-fill & Flex-grow )
  • Integrated Pager
  • Cell & Row Selection ( Single, Multi, Keyboard, Checkbox )
  • Fixed AND Fluid height
  • Left and Right Column Pinning
  • Row Detail View
  • Decoupled theme'ing with included Google Material theme
  • Light codebase / No external dependencies
  • AoT Compilation Support
  • Universal Support

Installation

To use ngx-datatable in your project install it via npm:

text
npm i @swimlane/ngx-datatable --save

Building

Run yarn build to build the project. The build artifacts will be stored in the dist/ directory.

Running tests

  • Run yarn test to execute the linter, prettier check, unit and end-to-end tests.

Release

  • Checkout master (git checkout master)
  • Pull master (git pull)
  • Refresh node modules (yarn install --frozen-lockfile)
  • Run tests (yarn test)
  • Examine log to determine next version (X.Y.Z)
  • Run git checkout -b release/X.Y.Z
  • Update version in projects/swimlane/ngx-datatable/package.json.
  • Update changelog in docs/CHANGELOG.md
  • Run yarn package to build the package
  • Run git commit -am "(release): X.Y.Z"
  • Run git tag X.Y.Z
  • Run git push origin HEAD --tags
  • Run yarn publish
  • Submit PR

Credits

ngx-datatable is a Swimlane open-source project; we believe in giving back to the open-source community by sharing some of the projects we build for our application. Swimlane is an automated cyber security operations and incident response platform that enables cyber security teams to leverage threat intelligence, speed up incident response and automate security operations.


Overview (`docs/README.md`)

ngx-datatable

ngx-datatable is a Angular component for presenting large and complex data.
It has all the features you would expect from any other table but in a light package
with no external dependencies. The table was designed to be extremely flexible and light;
it doesn't make any assumptions about your data or how you: filter, sort or page it.

It was originally built for modern browsers using TypeScript, CSS3 and HTML5 and Angular >=4.0.0.
This is the sister project of the angular-data-table
that is designed for Angular 1.x.

In The News

AngularAir Esp 76

{% youtube %}https://www.youtube.com/watch?v=Pj4orsvIp8c{% endyoutube %}

The project was featured on AngularAir where @amcdnl
spoke about the project, challenges and whats to come.

Development server

Run yarn start to serve the demo at http://localhost:4200/. The app will automatically reload if you change any of the source files.

Building

Run yarn build to build the project. The build artifacts will be stored in the dist/ directory.

Running tests

  • Run yarn test to execute the linter, prettier check, unit and end-to-end tests.

Release

  • Checkout master (git checkout master)
  • Pull master (git pull)
  • Refresh node modules (yarn install --frozen-lockfile)
  • Run tests (yarn test)
  • Examine log to determine next version (X.Y.Z)
  • Run git checkout -b release/X.Y.Z
  • Update version in projects/swimlane/ngx-datatable/package.json.
  • Update changelog in docs/CHANGELOG.md
  • Run yarn package to build the package
  • Run git commit -am "(release): X.Y.Z"
  • Run git tag X.Y.Z
  • Run git push origin HEAD --tags
  • Run yarn publish
  • Submit PR

Introduction Getting Started (`docs/introduction/getting-started.md`)

Getting Started

After Installing, include NgxDatatableModule
in your application module like:

javascript
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { NgxDatatableModule } from '@swimlane/ngx-datatable';

import { AppComponent } from './app.component';

@NgModule({
  declarations: [AppComponent],
  imports: [NgxDatatableModule, BrowserModule],
  bootstrap: [AppComponent]
})
export class AppModule {}

then in your app.component.ts you define a table like:

javascript
import { Component } from '@angular/core';

@Component({
  selector: 'app',
  template: `
    <div>
      <ngx-datatable [rows]="rows" [columns]="columns"> </ngx-datatable>
    </div>
  `
})
export class AppComponent {
  rows = [
    { name: 'Austin', gender: 'Male', company: 'Swimlane' },
    { name: 'Dany', gender: 'Male', company: 'KFC' },
    { name: 'Molly', gender: 'Female', company: 'Burger King' }
  ];
  columns = [{ prop: 'name' }, { name: 'Gender' }, { name: 'Company' }];
}

and you're off to the races!

For more examples, visit the
demos directory
in the source code!


CHANGELOG (`docs/CHANGELOG.md`)

CHANGELOG

HEAD (unreleased)

25.1.0

Features

  • Enhancement: Added support for Angular 22
  • Breaking: Removed support for Angular 19 and earlier versions
  • Feature: Lay out columns with a shared CSS grid (header/body via subgrid) and unify scrolling into a single scroll container
  • Feature: Re-measure dimensions via ResizeObserver instead of window:resize
  • Feature: Add DatatableSummaryRowDirective for custom summary row templates
  • Feature: datatable-row-def can optionally preserve measured column widths when cloned (preserveColumnWidthsOnClone)

Bug Fixes

  • Fix: Keep prior selection when shift-clicking after ctrl-click (#582)
  • Fix: Fill viewport with ghost loader rows on initial load
  • Fix: Wait for DOM updates before scrolling to an expanded tree row
  • Fix: Compute correct tree level when a child precedes its parent in tree rows
  • Fix: Ensure custom sort icons are applied
  • Fix: Allow sorting on mobile devices when reorderable is enabled
  • Fix: Add missing aria-sort on header cells
  • Fix: Fixing scroller Issue in datatable when multiple columns are there in datatable
  • Fix: Prevent flex mode from emitting negative column widths that invalidate CSS grid-template-columns (v25+)
  • Fix: Keep explicit column width in flex mode when flexGrow is unset (no longer requires canAutoResize=false)

Breaking Changes

  • Breaking: Removed support for Angular 19 and earlier versions
  • Breaking: Removed deprecated sort output; use (sortsChange) or [(sorts)] instead
  • Breaking: Removed deprecated select output; use (selectedChange) or [(selected)] instead
  • Breaking: Removed the visibility observer; recalculation is driven by ResizeObserver / layout

24.0.0

  • Enhancement: Added support for Angular 21
  • Breaking: Removed support for Angular 18 and earlier versions

24.0.0-alpha.0

  • Enhancement: Added support for Angular 21
  • Breaking: Removed support for Angular 18 and earlier versions

23.0.1

  • Fix: Fixing scroller Issue in datatable when multiple columns are there in datatable

22.0.0

  • Enhancement: Added support for Angular 20
  • Enhancement: Exporting isNullOrUndefined function and ColumnChangesService service to be used externally.
  • Breaking: Removed support for Angular 17 and earlier versions

22.0.0-alpha.1

  • Enhancement: Exporting isNullOrUndefined function and ColumnChangesService service to be used externally.

22.0.0-alpha.0

  • Enhancement: Added support for Angular 20
  • Breaking: Removed support for Angular 17 and earlier versions

21.1.0

  • Fix: Prevent browser page crash when user inputs large Arrays

21.0.0

  • Fix: Add missing package files from deployment
  • Breaking: support for angular 17-19

20.1.0

  • Chore: Support for angular 13+

20.0.0

  • Breaking: Update to angular 12

19.0.0

  • Breaking: Update to angular 11

18.0.0

  • Breaking: Update to angular 10

17.1.0

  • Feature: Add sorting: unset icon

17.0.0

  • Chore: explicitly only support ng9

16.1.1

  • Chore: Patch release to override 16.1.0

16.1.0

  • Fix: [selectAllRowsOnPage] is broken. (#1809)
  • Fix: Bug when using cellClass as string. (#1817)
  • Fix: Docs. (#1812, #1837, #1845, #1854)
  • Fix: redraw after recalculate (#1816)
  • Fix: undefined row index for rows in groups (#1857)
  • Chore: Add pretty-quick as a precommit hook using husky (#1841)
  • Chore: Bump dependencies (#1858, #1862, #1859)

16.0.3

  • Bug: Fix disappearing rows with vertical scrollbar, virtual scrolling & rowdetail auto height (#1799)
  • Bug: Fix memory leak due to created element not cleaned up (#1792)
  • Bug: do not collapse row details when row updated (#1778)

16.0.2

  • Bug: Remove barrel files because ng-packagr doesn't work well with them

16.0.1

  • Bug: Include styles, assets and themes in release

16.0.0

  • Breaking: the release files are not under the /release folder any more. Also, paths to themes and assets have changed. If you are importing any assets or styles from the release folder, you would need to update the paths.
  • Chore: Migrates the project to angular-cli, making it compatible with Ivy (#1738)
  • Feature: Implements global module config via forRoot (#1688)
  • Feature: Colors of material style can be modified by target application (#1651)
  • Bug: Fixes Exception in scoller component destroy (#1685)
  • Bug: Fixes issue 1686: column resizing issue in force columns mode (no horizontal scroll) when container get smaller (#1687)
  • Docs: Updates demo pages (#1738)

15.0.2

  • Fix: Fixes issue where footer pagination does not work when virtual scrolling is enabled (#1704)

15.0.1

  • Fix: Fixes issue where using conditional templates would not render them (#1701)

15.0.0

  • Breaking: Upgrade to angular 8 (#1697)
  • Fix: Module not found: Error: Can't resolve '.' (#1646)
  • Fix: trackByProp can't work. (#1622)

14.0.0

  • Breaking: Upgrade to angular 7
  • Fix: Fix compile error when using TemplateTypeCheck set to true (#1520)

13.1.0

  • Feature: Added support for tree grid (#1273)
  • Fix: Improve virtualization as a flag (#1297)
  • Fix: Fix issue when count is undefined #838 (#1499)
  • Fix: Fix usage withing prerendered SPA (#1438)

13.0.1

  • Fix: Run scroll event listeners inside angular zone (#1375)

13.0.0

  • Breaking: Fixes several issues related to the summary row feature #1418
  • Fix: DataTableColumnDirective Input Binding Changes #1384
  • Fix: angular version #1420
  • Fix: issues when running npm run build --prod #1410

12.0.0

  • Breaking: Upgraded to Angular 6 #1400
  • Feat: Added reorderable input #1261
  • Fix: Fixed rowHeight type in body component #1295
  • Fix: Fixed row selection for bootstrap theme #1357
  • Fix: Reflect minWidh & maxWidth props to body cell #1361

11.3.0

  • Feat: Added summary row #1233
  • Fix: Fixed issue wi
    th misaligned body content #1326
  • Fix: Fixed Default Sort Behavior Of Table With Custom Templates #1308
  • Chore: Fixed link in column api docs #1343
  • Chore: Fixed typo in docs #1342

11.2.0

  • Feat: Add resize handler for non-resizable columns #1225
  • Fix: Pager Component Accessibility #1259
  • Fix: Fix missing row with virtualization and scrollbarV #1235
  • Fix: Fall back to view mode when select field value doesn't change #1241
  • Fix: Fix virtual-paging #1229
  • Fix: Fix column scaling on resize #1236
  • Fix: Propagate sortDir changes to template #1243
  • Fix: Add setStylesByGroup() in set column prop #1244

11.1.7

  • Fix: Fix error w/ rows undefined on init

11.1.6

  • Bug: Ignore rxjs/operators
  • Feat: Ability to disable virtualization #1191
  • Feat: Universal Support #1178

11.1.5

  • Compat: Fix Angular 4.x Compat

11.1.4

  • Bug: Fix column templates not updating with loops/ifs
  • Bug: Fix sorting on cross browser
  • Chore: Switch to lettable operators

11.1.3

  • Bug: Angular SSR Event Undefined (#1144)

11.1.2

  • Bug: Fix total undefined (#1140)

11.1.1

  • Bug: Fix race case with rows

11.1.0

  • Perf: Better performance on scrolling y and x
  • Feature: Select All on Current Page (#1132)
  • Bug: Don't show empty on loading (#1139)

11.0.4

  • Bug: Fix Angular5 Aot Issue
  • Bug: Fix Vendor Prefix Error

11.0.1, 11.0.2, 11.0.3

  • Bug: Angular 5 bugs

11.0.0

  • Chore: Upgrade to Angular5

10.4.0

  • Feature: Ability to filter checkable rows (#1056)
  • Feature: Allow sorting based on whole row (#1074)
  • Bug: Fix protractor events (#1081)
  • Bug: Fix misalignment on smaller screens (#1081)

10.3.0

  • Feature: Bootstrap theme
  • Bug: Fix CSS for row grouping (#1053)
  • Bug: Fix group row values (#1034)
  • Bug: Fix cell overflow w/ fluid height (#1030)
  • Bug: Fix for column sort (#1018)
  • Bug: Strip HTML for null values (#966)
  • Bug: Update context in cell header (#935)
  • Bug: Add bounds to offset (#978)
  • Bug: Make selection apply to all rows (#974)

10.2.3

  • Bug: Fix checkbox not being shown #956
  • Bug: Fix IE displaying null #967
  • Bug: Fix emptry string is row is null #951

10.2.2

  • Bug: Recalculate limit properly #963

10.2.1

  • Bug: Detail Row Broken

10.2.0

  • Feature: Row Grouping

10.1.0

  • Feature: Row Hover Event
  • Bug: Columns are no longer mutated!
  • Bug: Fixes for Angular v5!
  • Bug: Fix expand all row detail not working #917
  • Chore: Remove useless jsdoc comments

10.0.5

  • Style: Material styles closer to spec
  • Bug: Non-sortable header showing pointer cursor

10.0.4

  • Perf: Changed everything internal to OnPush
  • Perf: Fixed header cell outlet cd
  • Bug: Fixed sort mutating original rows

10.0.3

  • Perf: Better performance in cells

10.0.2

  • Enhancement: Add rowIndex to row-detail template
  • Bug: Add index.css back to build

10.0.1

  • Bug: Fix old references to $$index and $$expanded
  • Bug: Add $$index in cell templates as rowIndex
  • Bug: Fix MouseEvent undefined in JIT (#893)

10.0.0

  • BREAKING: $$expanded is no longer on row of detail templates, use let-expanded to get pop now
  • Feature: Always center activated page on pager
  • Bug: Remove row mutations of $$index and $$expanded
  • Bug: Pagination broken on large number of rows
  • Bug: Strip HTML from title tags (#892)

9.3.1

  • Bug: More Universal Rendering Fixes (#795)
  • Chore: Build optimizations from new webpack version

9.3.0

  • Feature: Unviseral Rendering (#764)

9.2.0

  • Enhancement: Add header context menu event
  • Bug: Fix sort blowing up when undefined and adding new sort
  • Bug: Fix multi-selection key with Mac

9.1.0

  • Enhancement: Add more context to cells #720
  • Enhancement: Export Pager component #735
  • Bug: Header checkbox when row selection is changed #659
  • Bug: When rowClass() returns a string, the class is not properly added #710
  • Bug: Rename icons so don't conflict with other libs #729

9.0.0

  • BREAKING: Fixes for external pagination fixes. Index calculation change being last page = 0 + pageSize (#714, #138, #391)
  • Feature: Server-side virtual scrolling pagination
  • Demos: Deep linking of demo pages

8.2.1

  • Bug: Fix footer styles

8.2.0

  • Feature: Footer Templates

8.1.0

  • Feature: Dark Theme

8.0.1

  • Bug: Fix memory leak (#702)
  • Bug: Don't add column header title attribute when custom template provided (#643)
  • Bug: Only apply pointer to header text (#682)
  • Bug: Fix prop field name with dots (#596)
  • Bug: Virtual scroll + dynamic height in cell detail not working right (#703)
  • Bug: Fix dynamic row height not working right if using server-side pagination
  • Chore: Implement noImplicitAny (#671)

8.0.0

  • Breaking: Removed cssClass from columns in favor of explicit
  • Feature: Added explicit headerClass and cellClass
  • Feature: Add ability to have callback for those class getters
  • Bug: Fix checkbox select all not updating ui correctly

7.3.1

  • Bug: Fix resize handle drag triggering long press
  • Bug: Fix dragging trigging column sorting
  • Bug: Fix column re-ordering not working on FF

7.3.0

  • Feature: Dynamic row heights for virtual scrolling
  • Bug: Do not use document for universal support (#668)

7.2.1

  • Bug: Fix missing type

7.2.0

  • Feature: Allow for dynamic Detail Row heights (#653)
  • Feature: Numeric prop support via support array rows (#494)
  • Perf: Optimize sort code by caching valueGetter and compareFn outside loop.
  • Perf: Set ValueGetter on TableColumn.$$valueGetter
  • Bug: Alter setColumnDefaults to work with numeric prop values.

7.1.1

  • Perf: Fix memory leaks with templates (#464)
  • Bug: Fix row detail expanded and then collapsed not showing anything until scroll

7.1.0

  • Bug: Fix title not set on cell template (#629)
  • Chore: Update to official Angular4
  • Chore: Misc build dep updates

7.0.0

  • BREAKING: Update to Angular4!
  • Feature: Row classes (#571), (#348)
  • Bug: Show first page after sorting (#553)
  • Bug: When reordering and skipping a column, the column gets duplicated (#497), (#562), (#563)
  • Chore: Upgrade misc deps and lint fixes

NOTE: If you need support for ~Angular2, use version 6.x.

6.3.0

  • Bug: Perform sort when sort icon is clicked (#536)
  • Bug: Fix resize handle overlaped by label (#521)
  • Chore: Fix relative imports for rollup (#542)
  • Chore: Linting

6.2.1

  • Bug: Revert #516 causing server-side paging issue (#543)

6.2.0

  • Bug: Fix AoT builds with SCSS (#534)
  • Bug: Fix offset incorrect when filtering (#516)
  • Bug: Fix mouse press subscription cleanups (#522)
  • Bug: Fix header cell wrapper empty span (#504)
  • Bug: Fix selected count undefined in footer template (#537)
  • Bug: Fix orderable unsubscribe listeners (#538)
  • Chore: Update Angular and ZoneJS

6.1.2

  • Bug: Fix default sort (#475)

6.1.1

  • Bug: Fix tree-shaking issue (#511)

6.1.0

  • Feature: Add selected count in footer (#508)
  • Bug: Fix drag/drop/long-press (#506)
  • Bug: Fix row widths not set correctly (#510)
  • Perf: Better mouseup handling (#507)
  • Chore: Bump Depedencies

6.0.2

  • Bug: Move scss to release dir (#459)

6.0.1

  • Bug: Fix CSS not working with AoT (#459)
  • Chore: Fix ExtractText plugin causing build issue
  • Chore: Upgrade Angular 2.4.5

6.0.0 (2017-01-25)

  • BREAKING: Renamed datatable css class to ngx-datatable
  • BREAKING: Embedded core css file with Angular styleUrls
  • Enhancement: Allow sorting from inline templates (#431)
  • Enhancement: Fix re-ordering columns throwing errors (#438)
  • Enhancement: Add nice drag indicator to material theme
  • Chore: Update Depedencies

5.0.0

  • BREAKING: Re-worked all inputs, methods and outputs of row detail to its own container
  • Enhancement: Implement Finder/Explorer shift selection behavior
  • Bug: Fix reverse selection de-selecting first index in reverse
  • Bug: Fix row detail not rendering

4.2.0

  • Enhancement: Ability to add CSS Classes on Header/Column
  • Bug: Fix CPU Perf on Resort (#409)
  • Chore: Upgrade to Angular ^2.4.3
  • Chore: Correct RxJS Imports

4.1.0

  • Feature: Adding multi-click selection
  • Bug: Use tracking fn vs inline (#388)
  • Bug: Fix AoT header issue (#389)
  • Bug: Fix reorderable not being honored (#387)
  • Bug: Fix multi-select CTRL not working (#381)
  • Chore: Upgrade Angular to ^2.4.1
  • Docs: Multi-select

4.0.0

  • BREAKING!!!! - Renamed project from angular2-datatable to ngx-datatable
    and updated components from <swui-datatable> to <ngx-datatable>

3.0.0

  • BREAKING: Removed shiftMulti option, its not useful and creates odd scenarios
  • Bug: Permanently high CPU utilization after sorting (#359)
  • Bug: Fix checkbox showing in header if defined but not using checkbox select
  • Bug: Fix AoT errors (#370)
  • Bug: Fix build not outputing AoT files in correct directory
  • Bug: Fix checkbox selection not working w/ shift key
  • Chore: Upgrade Angular/Webpack

2.2.3

  • Bug: Fix header checkbox mutating selection array

2.2.2

  • Bug: Fix default selections and don't mutate selection arrow now

2.2.1

  • Bug: Fix AoT by reverting TypeScript upgrade until CLI is updated

2.2.0

  • Bug: Fix AoT private props (#352)
  • Bug: Added null chk to selection getter (#340)
  • Bug: multiShift not working after first page (#294)
  • Chore: Update Angular to 2.3.0
  • Chore: Update TypeScript to 2.1.x
  • Chore: Update RxJS to 5.0.0-rc.4
  • Chore: Update ZoneJS to 0.7.2
  • Demo: Add templates for Webpack plugin for Google Analytics

2.1.3

  • Bug: Fix footer not updating when all removes removed
  • Bug: Fix Add/Remove items in array not updating (#255)

2.1.2

  • Bug: Fix sizing method being debounced on view inits rather than just window resize.

2.1.1

  • Bug: Fix memory leak with visibility observer

2.1.0

  • Feature: Checkbox selection mode
  • Enhancement: Selection mode auto added to host class for easier styling
  • Style: Remove row active/select state when in cell mode of material theme
  • Bug: Force fill column mode w/ scrollbarH false allowing bleed when resized
  • Perf: Faster render time by adding css class via host
  • Perf: Debounce window resize calcs

2.0.0

  • BREAKING: Rename from datatable to swui-datatable (#320)
  • BREAKING: Redo how row-detail/cell/header templates are described in markup (#304)
  • BREAKING: Change Detection switched back to normal
  • Enhancement: Row Context Menu Event rowContextmenu (#331)
  • Bug: Set default value for selected (#314)
  • Bug: Fix widths being int vs float (#309)
  • Bug: Fix column resize not setting widths to the right (#308)
  • Bug: Fix row object mutations (#255)
  • Bug: Async Problem when using @Input (#253)
  • Bug: Sort doesn't work on the first click (#254)
  • Bug: Pagination "skip to last page" is not selected after click (#324)
  • Bug: ngFor Not working in the datatable-row-detail-template (#274)
  • Chore: Resolve all implicit anys (#330)
  • Chore: Bump Angular to latest 2.2.4

1.7.0

  • Enhancement: Add RxJS Support
  • Chore: Fix builds on windows

1.6.0

  • Bug: Column headers not re-ordering (#238)
  • Bug: Datatable doesn't sort data correctly when data changed (#284)
  • BREAKING: comparator now is a normal sort function arguments of propA, propB.

1.5.1

  • Bug: Custom comparator should return new array (#286)
  • Bug: Init selection to empty array (#285)

1.5.0

  • Enhancement: externalSorting input for simpler server-sorting usage (#281)
  • Enhancement: Add trackByProp for change detection with mutation of row data
  • Bug: Row height variable access protection (#280)
  • Chore: Upgrade to Angular 2.2.0
  • Demo: Inline editing updates
  • Demo: Live data refresh demo
  • Breaking: Remove refresh method per recommendation by @robwormald

1.4.1

  • Bug: Ignore next page when already at last (#223)
  • Chore: Redid Webpack Config to be clean
  • Chore: TESTS! TRAVIS BUILDS! COVERAGE REPORTING!

1.4.0

  • Enhancement: Added refresh API for updating table (#255)
  • Bug: Fix intersection observer type errors (#268)

1.3.1

  • Bug: Fix force column width distribution overriding new resize (#245)

1.3.0

  • Enhancement: selectCheck fn to prevent selection
  • Bug: Fix columns leaking event handlers
  • Bug: Fix column toggling errors (#245)
  • Bug: Fix AoT Metadata not creating

1.2.0

  • Bug: Fix columns loosing templates on resize (#252)
  • Bug: Fix pager not having right pages when hidden by default
  • Bug: Fix expressive column width as attribute with standard column distribution
  • Bug: Fix body columns not readjusting after window resize (#251)
  • Enhancement: Refactor emptyMessage and totalMessage to messages object
  • Enhancement: Huge perf improvement for tables hidden by default

1.1.0

  • Feature: NGC Complation
  • Bug: Null value in deepValueGetter (#243)
  • Chore: Update Depedencies

1.0.0

  • Feature: Cell Selection and Keyboard Navigation
  • Feature: activation events
  • Enhancement: OnPush all the things!
  • Enhancement: Add totalMessage option for localization
  • Enhancement: Demo Page
  • Enhancement: Page Count Formatted
  • Enhancement: Automatically format column prop when no name passed
  • Enhancement: Add ability to pass false to comparator for sort handling via event
  • Bug: Window resize not updating rows in virtual scrolling
  • Chore: Switch to SemVer
  • BREAKING: TableOptions has been removed and options are Input on component now
  • BREAKING: TableColumn class has been removed, just pass normal objects
  • BREAKING: Event names has been renamed using Angular2 standards
  • BREAKING: Components have been renamed to Angular2 standards
  • BREAKING: Removed StateService

0.12.0

  • Bug: Return empty string on undefined deep values (#232)
  • Bug: Fix force fill alog (#218)
  • Enhancement: Support for other icon types (#235)
  • Enhancement: Add ability to identify rows for proper selection (#154)

0.11.2

  • Enhancement: Add ability to define css icon classes for pager / header
  • Chore: Uprade to Angular 2.1.1

0.11.1

  • Chore: Polish on new build

0.11.0

  • Chore: New build process
  • Bug: Fix detail row bug (#212)

0.10.1

  • Bug: Fix $$expanded undefined with server paging (#210)

0.10.0

  • Chore: Upgrade to Angular 2.1.0 (#202)
  • Chore: Removed engine restrictions (#195)
  • Bug: windows builds with node-sass (#207)
  • Bug: resizing not closing correctly (#196)
  • Bug: Fix height paging (#208)
  • Enhancement: Improve Active CSS (#204)
  • Enhancement: Add Empty Message (#194)
  • Enhancement: Add deep value getter to sortRows function (#181)
  • Enhancement: Sort Classes are applied to body cells (#166)
  • Enhancement: AoT Compatibility (#199)
  • Feature: Row Detail (#201)

0.9.3

  • Column resize sometimes gives weird behaviour on mouse resize/click (#155)
  • Fix order of setters in DataTable ngOnChanges (#179)
  • Remove document event listener subscription leak in draggable & resizeable
  • Fix setScrollTop undefined error (#182)

0.9.2

  • Fix name being undefined introduced in 0.9.0 release

0.9.1

  • Export component references for external consumption (#176)

0.9.0

  • Fix accidental breaking change of renaming HeaderCell column property to model. See commit.
  • Ensure minWidth and maxWidth values are specified saved as numbers (#167)
  • Add row double click option (#168)

0.8.0

  • Added the ability to define header templates expressively
    Breaking Change! Renamed template to cellTemplate in column options

0.7.4

  • Removed #142 in favor of style height
  • Fixed issue with height + scrollbarV not sizing right
  • Fix limit not applied (#133)
  • Fix sort not resetting to top of page (#136)
  • Added option validation

0.7.3

  • Huge perf bumps (#149)

0.7.2

  • Build fixes

0.7.1

  • Removed template wrapper in favor of native template outlet

0.7.0

  • Upgrade Angular 2.0.1 & ZoneJS
  • Angular Code Style Compliance (#147)
  • Fix initial load of rows jumbled (#156)
  • Update row/options setting to ngOnChanges (#151)
  • Fix column height not set correctly (#144)

0.6.1

  • Virtual Scrolling Emits Paging (#130)

0.6.0

  • Update to Angular 2.0.0!
  • Fix horizontal header issue (#129)

0.5.1

  • Fixed Multiple Tables on Same Page (#103)
  • Fix TS Helpers not being included in release (#107)
  • Update onPage API to reflect docs (#116)

0.5.0

  • Upgrade to Angular2 RC7

SUMMARY (`docs/SUMMARY.md`)

Summary


Contributing Building (`docs/contributing/building.md`)

Building

This project uses npm tasks for builds.

Pre-reqs

  • Node >= 6.0.0
  • Angular CLI
  • TypeScript >= 2.0.0

Commands

  • npm start: Starts Webpack dev server
  • npm run release: Builds code to dist folder
  • npm run test: Runs E2E Tests
  • npm run package: Runs builds, packages and copies results to ./release

Depedencies

  • webpack (npm install webpack)
  • webpack-dev-server (npm install webpack-dev-server)
  • karma (npm install karma-cli)
  • protractor (npm install protractor)
  • typescript (npm install typescript)

Contributing Community (`docs/contributing/community.md`)

Community

Below is a list of community contributions and projects that use the table.

  • ng2-inline-editor - inline edit cell values with ng2-inline-editor and ngx-datatable projects.

If you have a project using the table and would love to share with the community, please reach out on
gh issues and we would love to add it to the growing list!


Contributing Credits (`docs/contributing/credits.md`)

Credits

ngx-datatable is a Swimlane open-source project; we believe in
giving back to the open-source community by sharing some of the projects we build for our application.
Swimlane is an automated cyber security operations and incident response platform that enables cyber security
teams to leverage threat intelligence, speed up incident response and automate security operations.

Contributors

{% GitHubContributors %}
{% endGitHubContributors %}


Contributing Guidelines (`docs/contributing/guidelines.md`)

Guidelines

We would love for you to contribute to our project and help make it ever better!
As a contributor, here are the guidelines we would like you to follow.

Found an Issue?

If you find a bug in the source code or a mistake in the documentation, you can help us
by submitting an issue to our GitHub Repository. Including an issue reproduction
(via CodePen, JsBin, Plunkr, etc.) is the absolute best way to help the team quickly diagnose the
problem. Screenshots are also helpful.

You can help the team even more and submit a Pull Request with a fix.

Want a Feature?

You can request a new feature by submitting an issue to our GitHub Repository.
If you would like to implement a new feature, please submit an issue with a proposal for your work first,
to be sure that we can use it. Please consider what kind of change it is:

  • For a Major Feature, first open an issue and outline your proposal so that it can be discussed.
    This will also allow us to better coordinate our efforts, prevent duplication of work, and help you
    to craft the change so that it is successfully accepted into the project.
  • Small Features can be crafted and directly submitted as a Pull Request.

Issue Etiquette

Before you submit an issue, search the archive, maybe your question was already answered.

If your issue appears to be a bug, and hasn't been reported, open a new issue. Help us
to maximize the effort we can spend fixing issues and adding new features by not reporting
duplicate issues. Providing the following information will increase the chances of your issue being dealt with quickly:

  • Overview of the Issue - if an error is being thrown a non-minified stack trace helps
  • Angular and ngx-datatable Versions - which versions of Angular and ngx-datatable are affected
  • Motivation for or Use Case - explain what are you trying to do and why the current behavior is a bug for you
  • Browsers and Operating System - is this a problem with all browsers?
  • Reproduce the Error - provide a live example (using CodePen, JsBin, Plunker, etc.) or a unambiguous set of steps
  • Screenshots - Due to the visual nature of ngx-datatable, screenshots can help the team triage issues far more quickly than a text description.
  • Related Issues - has a similar issue been reported before?
  • Suggest a Fix - if you can't fix the bug yourself, perhaps you can point to what might be causing the problem (line of code or commit)

Introduction Architecture (`docs/introduction/architecture.md`)

Architecture

Manifesto

There is some things that it doesn't do nor do we plan to do. Lets say you have a requirement to have the
ability to edit cell values in the row. Thats a awesome feature but somewhat catered to your use case.
How do you invoke the edit? What type of control do you show in the cell? If its a date,
do you have controls for that? Its a slippery slope...if you do want to do that you can use the
expressive column templates to put whatever components inside your table you want.

What we wanted to do is design a table component that isn't bloated with
features that won't fit every use case but instead make a component that does
what it does the best possible and is flexible enough to allow you to do what you need
to do to solve your requirement.

Some examples of the things we don't plan to build in this project are:

  • Export such as CSV
  • Context Menus
  • Column Filters
  • Column Toggling

If you are interested in building something like that for this project, I'm happy
to help point you in the right direction and would be happy to list a link as a
extension.


Introduction Cd (`docs/introduction/cd.md`)

Change Detection

The table implements OnPush change detection which means the dirty checking checks for immutable
data types. That means if you do object mutations like:

javascript
this.rows[i]['gender'] = 'Female';

The table will not detect a change! Instead if you do a change like this, you need to do:

javascript
this.rows[i]['gender'] = 'Female';
this.rows = [...this.rows];

This will cause the table to detect the change and update. Some might have concerns that
this is a pricey operation, however, it is MUCH cheaper than running ngDoCheck and
constantly diffing the array.

For more information, I recommend this article Angular Change Detection Explained.


Introduction Column Modes (`docs/introduction/column-modes.md`)

Column Modes

Column modes allow you to have a variety of different ways to apply column width distribution
to the columns. The table comes with 3 modes; standard, flex, force.

Standard

Columns are distributed given the width's defined in the column options.

Flex

Flex mode distributes the width's grow factor relative to other columns.
It works the same as the [flex-grow API](http =//www.w3.org/TR/css3-flexbox/) in CSS.
Basically it takes any available extra width and distribute it proportionally
according to each column's flexGrow value.

Flex is not suggested for when using scrollH.

Force

Force mode forces the widths of the columns to distribute equally but overflowing when
the min-width of each column is reached. The rules are:

  • If combined widths are less than the total width of the grid,
    proportion the widths given the min / max / normal widths to fill the width.

  • If the combined widths, exceed the total width of the grid, use the standard widths.

  • If a column is resized, it should always use that width.

  • The proportional widths should never fall below min size if specified.

  • If the grid starts off small but then becomes greater than the size ( + / - )
    the width should use the original width; not the newly proportioned widths.

Force is usually the ideal column distribution method when columns do not need
to be a fixed sized.


Introduction Features (`docs/introduction/features.md`)

Features

The table was designed to be extremely flexible and light; it doesn't make any assumptions about your data or
how you: filter, sort or page it. That said, we wanted to keep the features strictly related to dealing
with the data rather than implementing complex filtering/etc that is often very use-case specific.
The current features include:

  • Handle large data sets ( Virtual DOM )
  • Expressive Header and Cell Templates
  • Horizontal & Vertical Scrolling
  • Column Reordering & Resizing
  • Client/Server side Pagination & Sorting
  • Intelligent Column Width Algorithms ( Force-fill & Flex-grow )
  • Integrated Pager
  • Cell & Row Selection ( Single, Multi, Keyboard, Checkbox )
  • Fixed AND Fluid height
  • Left and Right Column Pinning
  • Row Detail View
  • Decoupled theme'ing with included Google Material theme
  • Light codebase / No external dependencies

Roadmap

We are really excited about the table and wanted to get it out into the open as quickly as
possible so we had to delay some of the features but we plan to add the following:

  • Touch selection
  • Tree Grids
  • Row Grouping

Alternatives

This might not be the best fit for you given the above, there are some other great solutions
and some this project borrows from; heres a short list:


Introduction Installing (`docs/introduction/installing.md`)

Installing

You can grab the latest release from the Releases Page
in Github or via NPM.

  • npm install @swimlane/ngx-datatable

CSS

If you want to use material theme, include ./themes/material.css. For more information, visit the 'Themes' section.

Developing

If you are wanting to run the demos locally, just do:

  • npm i
  • npm start
  • Browse to http://localhost:9999

Introduction Themes (`docs/introduction/themes.md`)

Themes

Out of the box, the data-table is not styled. This gives you maximum flexibility.

There is a separate material theme distributed with data-table. In order to use it, you need to
include that in your application themes/material.css and add the CSS class material to your data-table.

This is a simple way to apply the style of the demo.

scss
@use '~@swimlane/ngx-datatable/index.css';
@use '~@swimlane/ngx-datatable/themes/material.scss';
@use '~@swimlane/ngx-datatable/assets/icons.css';

You can just add above to your scss file and then specify the class of your ngx-datatable to <ngx-datatable class="material">

CSS Classes

  • ngx-datatable: Master Table class

    • fixed-header: The header is fixed on the table
  • datatable-header: Header row class

    • datatable-header-cell: Header cell class

      • resizeable: Cell resizeable class
      • sortable: Cell drag/drop sortable class
      • longpress: Cell long-press activated
      • dragging: Cell dragging activated
      • sort-active: Sort active on column
      • sort-asc: Sort active on column with ascending applied
      • sort-desc: Sort active on column with descending applied
    • datatable-header-cell-label: Header cell text label

      • draggable: Header cell draggable class
  • datatable-body-row: Body row class

    • datatable-row-even: Odd row class
    • datatable-row-odd: Even row class
      • datatable-body-cell: Body cell class
        • sort-active: Sort active on column
        • sort-asc: Sort active on column with ascending applied
        • sort-desc: Sort active on column with descending applied

Universal Server Side Rendering (`docs/universal/server-side-rendering.md`)

To run ngx-datatable on a server using Angular Universal you must implement 2 services. Below are examples of these
services:

  1. DimensionsHelper
  2. ScrollbarHelper

If you take the default implementation of these 2 services they do not work on server for valid reasons. There is no viewport on server and there is no scrollbar on server. If you take these services as they are you will get an error like this:

text
this.document.createElement is not a function
          at ScrollbarHelper.getWidth
text
ERROR TypeError: this.element.getBoundingClientRect is not a function

Example Server side Dimensions helper

This service must send back the dimensions of the grid or fallback to a default width.

I am using the ideas about dimensions from client hints that I set on the signin page. http://httpwg.org/http-extensions/client-hints.html

typescript
import { ScrollbarHelper } from '@swimlane/ngx-datatable';
import { Injectable, Inject } from '@angular/core';
import { Request } from 'express';
import { REQUEST } from '@nguniversal/express-engine/tokens';
import { DimensionsHelper } from '@swimlane/ngx-datatable';

@Injectable()
export class ServerDimensionsHelper extends DimensionsHelper {
  constructor(@Inject(REQUEST) private request: Request) {
    super();
  }

  getDimensions(element: Element): ClientRect {
    const width = parseInt(this.request.cookies['CH-DW'], 10) || 1000;
    const height = parseInt(this.request.cookies['CH-DH'], 10) || 800;

    const adjustedWidth = width;
    const adjustedHeight = height;

    return {
      height: adjustedHeight,
      bottom: 0,
      top: 0,
      width: adjustedWidth,
      left: 0,
      right: 0
    };
  }
}

Scrollbar helper

In this case I just returned the scrollbar width based on what I used for css styling

typescript
import { ScrollbarHelper } from '@swimlane/ngx-datatable';
import { Injectable, Inject } from '@angular/core';
import { DOCUMENT } from '@angular/common';

@Injectable()
export class ServerScrollBarHelper extends ScrollbarHelper {
  width: number;

  constructor(@Inject(DOCUMENT) document) {
    super(document);
    this.width = 16; // use default value
  }

  getWidth(): number {
    return this.width;
  }
}

I then added these two services using @NgModule providers

typescript
providers: [
  {
    provide: ScrollbarHelper,
    useClass: ServerScrollBarHelper
  },
  {
    provide: DimensionsHelper,
    useClass: ServerDimensionsHelper
  }
];

Api Column Inputs (`docs/api/column/inputs.md`)

Table Column Options

`name`: `string`

Column label. If none specified, it will use the prop value and decamelize it.

`prop`: `string`

The property to bind the row values to. If undefined, it will camelcase the name value.

`flexGrow`: `number`

The grow factor relative to other columns. Same as the flex-grow API.
It will any available extra width and distribute it proportionally according to all columns' flexGrow values. Default value: 0

`minWidth`: `number`

Minimum width of the column in pixels. Default value: 100

`maxWidth`: `number`

Maximum width of the column in pixels. Default value: undefined

`width`: `number`

The width of the column by default in pixels. Default value: 150

`resizeable`: `boolean`

The column can be resized manually by the user. Default value: true

`comparator`

Custom sort comparator, used to apply custom sorting via client-side.
Function receives five parameters, namely values and rows of items to be sorted as well as direction of the sort ('asc'|'desc'):

text
(valueA, valueB, rowA, rowB, sortDirection) => -1|0|1

NOTE: Compare can be a standard JS comparison function (a,b) => -1|0|1 as additional parameters are silently ignored.
See MDN for more info.

`sortable`: `boolean`

Sorting of the row values by this column. Default value: true

`draggable`: `boolean`

The column can be dragged to re-order. Default value: true

`canAutoResize`: `boolean`

Whether the column can automatically resize to fill extra space. Default value: true

`cellTemplate`: `TemplateRef`

Angular TemplateRef allowing you to author custom body cell templates

`headerTemplate`: `TemplateRef`

Angular TemplateRef allowing you to author custom header cell templates

`checkboxable`: `boolean`

Indicates whether the column should show a checkbox component for selection. Only
applicable when the selection mode is checkbox.

`headerCheckboxable`: `boolean`

Indicates whether the column should show a checkbox component in the header cell.
Only applicable when the selection mode is checkbox.

`headerClass`: `string|Function`

Header CSS classes to apply to the header cell

`cellClass`: `string|Function`

Cell classes to apply to the body cell

`frozenLeft`: `boolean`

Determines if the column is frozen to the left. Default value: false

`frozenRight`: `boolean`

Determines if the column is frozen to the right. Default value: false

`pipe`: `PipeTransform`

Custom pipe transforms. Default value: undefined


Api Detail Inputs (`docs/api/detail/inputs.md`)

Row Detail Options

`template`: `TemplateRef`

Template to use in the detail row. Example:

text
<ng-template let-row="row">
  <div>
    <div><strong>Address</strong></div>
    <div>{{row.address.city}}, {{row.address.state}}</div>
  </div>
</ng-template>

`rowHeight`: `Number|Function`

Height of the detail row.

Template

html
<ngx-datatable-row-detail [rowHeight]="getHeight" #myDetailRow (toggle)="onDetailToggle($event)">
  <ng-template let-row="row" ngx-datatable-row-detail-template>
    <div><strong>Address</strong></div>
    <div>{{row.address.city}}, {{row.address.state}}</div>
  </ng-template>
</ngx-datatable-row-detail>

Typescript

javascript
getHeight(row: any, index: number): number {
  return row.someHeight;
}

Api Detail Methods (`docs/api/detail/methods.md`)

Row Detail Methods

`collapseAllRows()`

Collapse all row details when using row detail templates.

`expandAllRows()`

Expand all row details when using row detail templates.

`toggleExpandRow(row)`

Toggle expand/collapse a row detail when using row detail templates.


Api Detail Outputs (`docs/api/detail/outputs.md`)

Row Detail Outputs

All outputs are Angular EventEmitterers.

`toggle`

Row detail row was toggled.

text
{
  type: 'all' || 'row'
  value: boolean || row object
}

Api Row Row Def (`docs/api/row/row-def.md`)

Custom row wrapper

Use to pre-apply directives at row level.

`rowDef`

Directive to be applied on ng-template.

`datatable-row-def`

Component to be used as content of ng-template.
Apply your custom row level directive/class on this component. Example:

Template

html
<ng-template rowDef>
  <datatable-row-def applyYourCustomDirectiveHereForRow />
</ng-template>

Api Table Inputs (`docs/api/table/inputs.md`)

Table Inputs

`columnMode`

Method used for setting column widths

Value Description Default
standard Distributes based on widths x
flex Uses flex-grow API
force Distributes proportionally

`columns`

Array of columns to display

`count`

Total count of all rows. Default value: 0

`cssClasses`

Custom CSS classes that can be defined to override the icons classes for up/down in sorts and
previous/next in the pager. Defaults:

text
sortAscending: 'datatable-icon-down',
sortDescending: 'datatable-icon-up',
pagerLeftArrow: 'datatable-icon-left',
pagerRightArrow: 'datatable-icon-right',
pagerPrevious: 'datatable-icon-prev',
pagerNext: 'datatable-icon-skip'

`externalPaging`

Use external paging instead of client-side paging. Default value: false

`externalSorting`

Use external sorting instead of client-side sorting. Default value: false

`footerHeight`

The height of the footer in pixels. Pass a falsey for no footer. Default value: 0

`headerHeight`

The height of the header in pixels. Pass a falsy value for no header. Default value: 30

`messages`

Static messages in the table you can override for localization.

text
{
  // Message to show when array is presented
  // but contains no values
  emptyMessage: 'No data to display',

  // Footer total message
  totalMessage: 'total',

  // Footer selected message
  selectedMessage: 'selected',

  // Pager screen reader message for the first page button
  ariaFirstPageMessage: 'go to first page',

  // Pager screen reader message for the previous page button
  ariaPreviousPageMessage: 'go to previous page',

  // Pager screen reader message for the n-th page button.
  // It will be rendered as: `{{ariaPageNMessage}} {{n}}`.
  ariaPageNMessage: 'page',

  // Pager screen reader message for the next page button
  ariaNextPageMessage: 'go to next page',

  // Pager screen reader message for the last page button
  ariaLastPageMessage: 'go to last page'
}

`limit`

Page size to show. Default value: undefined

`loadingIndicator`

Show the linear loading bar. Default value: false

`offset`

Current offset ( page - 1 ) shown. Default value: 0

`reorderable`

Column re-ordering enabled/disabled. Default value: true

`swapColumns`

Swap columns on re-order columns or move them. Default value: true

`rowHeight`: `Function|number|undefined`

The height of the row.

When virtual scrolling is not in use, you can pass undefined for fluid heights.

If using virtual scrolling, you must pass a function or a number to calculate
the heights.

Using a function, you can set the height of individual rows:

text
(row) => {
  // set default
  if (!row) return 50;

  // return my height
  return row.height;
}

`rowIdentity`

Function for uniquely identifying a row, used to track and compare when displaying and selecting rows. Example:

text
(row) => {
  return row.guid;
}

`rows`

Array of rows to display.

`scrollbarH`

Use horizontal scrollbar. Default value: false

`scrollbarV`

Use vertical scrollbar for fixed height vs fluid. This is necessary for virtual scrolling. Default value: false

`selectCheck`

A boolean or function you can use to check whether you want
to select a particular row based on a criteria. Example:

text
(row, column, value) => {
  return value !== 'Ethel Price';
}

`displayCheck`

Function to determine whether to show a checkbox for a row. Example:

text
(row, column, value) => {
  return row.name !== 'Ethel Price';
}

`selected`

List of row objects that should be represented as selected in the grid. Rows are compared using
object equality. For custom comparisons, use the selectCheck function.

Default value: []

`selectionType`

Row selection mode

| Value | Description | Default |
| :------------- | :---------------------------------------------------- | ------- | ----------------------- | --- |
| undefined | false | null | Rows cannot be selected | x |
| "single" | One row can be selected at a time | |
| "cell" | One cell can be selected at a time | |
| "multi" | Multiple rows can be selected using Ctrl or Shift key | |
| "multiClick" | Multiple rows can be selected by clicking | |
| "checkbox" | Multiple rows can be selected using checkboxes | |

`sorts`

Ordered array of objects used to determine sorting by column. Objects contain the column name, prop, and sorting direction, dir. Default value: []. Example:

javascript
[
  {
    prop: 'name',
    dir: 'desc'
  },
  {
    prop: 'age',
    dir: 'asc'
  }
];

`sortType`

Sorting mode, whether "single" or "multi". In "single" mode, clicking on a column name
will reset the existing sorting before sorting by the new selection. In multi selection mode,
additional clicks on column names will add sorting using multiple columns.

Default value: "single"

`trackByProp`

A property on the row object that uniquely identifies the row. Example: "name"

`rowClass`

Function used to populate a row's CSS classes. The function will take a row and
return a string or object, as shown below:

text
(row) => {
  return {
    'old': row.age > 50,
    'young': row.age <= 50,
    'woman': row.gender === 'female',
    'man': row.gender === 'male'
  }
}

`virtualization`

Use virtual scrolling. Default: true


Api Table Methods (`docs/api/table/methods.md`)

Table Methods

`recalculate()`

Recalculate the grid sizes.


Api Table Outputs (`docs/api/table/outputs.md`)

Table Outputs

All outputs are Angular EventEmitterers.

`activate`

A cell or row was focused via keyboard or mouse click.

text
{
  type: 'keydown'|'click'|'dblclick'
  event
  row
  column
  value
  cellElement
  rowElement
}

`page`

The table was paged either triggered by the pager or the body scroll.

text
{
  count
  pageSize
  limit
  offset
}

`reorder`

Columns were re-ordered.

text
{
  column
  newValue
  prevValue
}

`resize`

Column was resized.

text
{
  column
  newValue
}

`tableContextmenu`

The context menu was invoked on the table.

text
{
  event,
  type,
  content
}

`scroll`

Body was scrolled typically in a scrollbarV:true scenario.

text
{
  offsetX
  offsetY
}

`select`

A cell or row was selected.

text
{
  selected
}

`sort`

Column sort was invoked.

text
{
  sorts
  column
  prevValue
  newValue
}

--- METRICS ---