ngx-datatable Documentation

ngx-datatable is a flexible, lightweight Angular data table designed to handle large datasets without making assumptions about your data processing logic (filtering, sorting, or paging).

Key capabilities include:

• Performance: Handles large datasets using a Virtual DOM.
• Layout: Horizontal & vertical scrolling, fixed or fluid height, and intelligent column width algorithms (Force-fill & Flex-grow).
• Column Management: Column reordering, resizing, and left/right column pinning.
• Data Interaction: Client/server-side pagination and sorting, integrated pager, and row detail views.
• Selection: Cell and row selection supporting single, multi, keyboard, and checkbox modes.
• Customization: Expressive header and cell templates, and decoupled theming (includes a Google Material theme).
• Architecture: Light codebase with no external dependencies.

To maintain flexibility and avoid bloat, the following features are not built into the core library:

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

If you require these features, you should implement them using custom column templates or look for community extensions.

In force mode, columns are forced to distribute equally but will overflow when the min-width of each column is reached. This is often the ideal method when columns do not need to be a fixed size.

Behavior Rules:

• If combined widths are less than the total grid width, it proportions widths (using min / max / normal widths) to fill the space.
• If combined widths exceed the total grid width, it reverts to using standard widths.
• If a column is resized, it maintains that specific width.
• Proportional widths will never fall below the specified min size.
• If the grid size changes (larger or smaller) after the initial load, the table uses the original widths rather than newly proportioned widths.

To run ngx-datatable on a server using Angular Universal, you must provide custom implementations for DimensionsHelper and ScrollbarHelper. The default implementations rely on browser-specific APIs like document.createElement or getBoundingClientRect, which are unavailable on the server and will cause TypeError exceptions.

You must extend these services and provide them in your @NgModule providers to ensure the grid can resolve dimensions and scrollbar widths during the server-side rendering process.

To use ngx-datatable in your project, you must import NgxDatatableModule from @swimlane/ngx-datatable and add it to the imports array of your @NgModule (typically in app.module.ts).

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 {}

In flex mode, the table distributes width based on a column's flexGrow factor relative to other columns, behaving similarly to the CSS flex-grow API. It takes any available extra width and distributes it proportionally according to each column's flexGrow value.

Note: flex mode is not suggested when using horizontal scrolling (scrollH).

To apply custom directives or classes at the row level in ngx-datatable, use a combination of the rowDef directive and the datatable-row-def component within an ng-template.

1. Define an <ng-template> and apply the rowDef directive to it.
2. Inside the template, use the <datatable-row-def> component.
3. Apply your custom directive, component, or CSS class directly onto the <datatable-row-def> element.

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

The ngx-datatable is unstyled by default to provide maximum flexibility. To use the built-in Material theme, you must import the necessary styles into your application and apply the material CSS class to the <ngx-datatable> component.

1. Import the styles in your global SCSS file.
2. Add class="material" to your <ngx-datatable> element.

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

<ngx-datatable class="material">
</ngx-datatable>