ngx-datatable¶

Usage¶

It supports sorting, filtering, paging, selection, virtualization, and keyboard interaction, while remaining flexible about data handling.

When to use¶

• To handle large datasets.
• When sorting, filtering, paging, or selection is required.
• To support column reordering.
• To support empty states (client or server).
• To support server-side filtering and sorting.
• To support grouped or tree rows
• To support row dragging.
• To support sticky columns.
• When looking for a free open-source solution.

Code¶

Note: The ngx-datatable implements change detection based on immutable table data. E.g. when only the content of a particular cell has changed, this change is not detected by the ngx change detection. See also the remark in the ngx-datatable documentation.

Usage¶

ngx-datatable is an Angular component for presenting large and complex data. The table is designed to be flexible and light. It doesn't make any assumptions about the data or how you filter, sort or page it. Check out the full documentation, demos and the demo code for more information!

import { NgxDatatableModule } from '@siemens/ngx-datatable';
import { SI_DATATABLE_CONFIG, SiDatatableModule, provideSiDatatableConfig } from '@siemens/element-ng/datatable';

// standalone apps
export const APP_CONFIG: ApplicationConfig = {
  providers: [
    ...
    provideSiDatatableConfig()
    // For smaller row heights:
    // provideSiDatatableConfig({rowHeight: SI_DATATABLE_CONFIG.rowHeightSmall})
  ]
};

// module based apps
@NgModule({
  imports: [
    NgxDatatableModule.forRoot(SI_DATATABLE_CONFIG),
    // For smaller row heights:
    // NgxDatatableModule.forRoot({ ...SI_DATATABLE_CONFIG, rowHeight: SI_DATATABLE_CONFIG.rowHeightSmall }),
    SiDatatableModule,
    // ...
  ]
})

Style configuration¶

No additional configuration is necessary as everything is already provided in the Element theme.

Keyboard interaction¶

To have the correct keyboard interaction, use the siDatatableInteraction directive.

Right align columns¶

There is a small but powerful trick how to right align columns with ngx-datatable. Notice how the Age column is right aligned in the example below. In the TypeScript code you can see that the table columns support two properties called headerClass and cellClass that can be used to apply a CSS class to the column header as well as the column's body cells:

{
  headerClass: 'justify-content-end', // right align column header
  cellClass: 'text-align-right-cell' // right align body cell
}

For the headerClass you can use the existing flex utility class justify-content-end to right align the column header. For the cellClass you have to define your own custom class text-align-right-cell and add the following SCSS code in your stylesheet:

::ng-deep {
  // center align datatable cell
  .text-align-right-cell .datatable-body-cell-label {
    flex: 1;
    text-align: end;
  }
}

Striped rows¶

Add table-striped next to table-element on <ngx-datatable> to distinguish alternating body rows, like the HTML table variant of the same name.

<ngx-datatable class="table-element table-striped">
  <!-- Table content -->
</ngx-datatable>

Striping is based on the row index, so it stays stable while scrolling virtualized rows. Hover, selection and focus states take precedence over the striping.

Client-side paging, sorting and selection options¶

• Use class="table-element" on <ngx-datatable>.
• Use the pagination component as custom footer template with ngx-datatable-footer and map inputs and outputs.

Server-side paging¶

Datatable component configured for server-side paging and lazy loading.

Vertical scroll¶

This example shows a table that grows to the maximum available height, using the layout-fixed-height class (see also Content Layouts). The property scrollbarV is used to enable vertical scrolling within the table. Enabling scrollbarVDynamic removes the scrollbar width from the row width only when actually needed.

Infinite scroll¶

Datatable component configured for server-side virtual paging. The data is loaded in pages from the server.

Empty state¶

Use the <si-empty-state></si-empty-state> for an empty table.

Selection¶

Datatable with a selection. Use the datatableInteractionAutoSelect input of the siDatatableInteraction directive to have it automatically select on keyboard navigation.

Filter and sort¶

Responsive¶

Fix height¶

Sticky columns with horizontal scroll¶

Reordering rows using Angular CDK Drag and Drop¶

Column management¶

Resizing¶

Datatables do have a fixed, automatically updated size, assumed during their initial rendering and refreshed during screen-size changes. However, they are not automatically refreshed in case their parent container changes size. It is the responsibility of a consuming application to invoke a recalculation if such an event occurs. Such a recalculation can be initiated by using the recalculate() function, exposed by the component.

// ...

@ViewChild(DatatableComponent) table?: DatatableComponent;

// ...

resizeTable() {
  setTimeout(() => this.table?.recalculate());
}

Note: For the component to obtain the correct size information, the recalculation has to happen after the actual resizing event. To ensure that, the setTimeout() has to be used.

The recalculation can either be triggered whenever changes on the DOM are made (e.g. when panels are collapsed/expanded) or by using Element's siResizeObserver directive. If you use siResizeObserver directive ensure that you have imported SiResizeObserverDirective in your standalone component or module.

<ngx-datatable (siResizeObserver)="resizeTable()" ...></ngx-datatable>

DatatableComponent API Documentation¶

Input Properties¶

Output Properties¶

Methods¶

SiDatatableInteractionDirective API Documentation¶

Input Properties¶

Types Documentation¶

// old
<ngx-datatable [columnMode]="ColumnMode.force"></ngx-datatable>
// new
<ngx-datatable [columnMode]="'force'"></ngx-datatable>

const column: TableColumn = {
  // before
  pipe: { transform: value => doTransform(value) },
  // after
  cellValueTransform: ({ value, row, column }) => doTransform(value),
}

// old
<ngx-datatable [selectionType]="SelectionType.multi"></ngx-datatable>
// new
<ngx-datatable [selectionType]="'multi'"></ngx-datatable>

// old
const sortType: SortType = SortType.single;
// new
const sortType: SortType = 'single';

// old
<ngx-datatable [columnMode]="ColumnMode.force"></ngx-datatable>
// new
<ngx-datatable [columnMode]="'force'"></ngx-datatable>

// old
<ngx-datatable [selectionType]="SelectionType.multi"></ngx-datatable>
// new
<ngx-datatable [selectionType]="'multi'"></ngx-datatable>

// old
const sortType: SortType = SortType.single;
// new
const sortType: SortType = 'single';