Import


import {DataTableModule} from 'primeng/datatable';

Getting Started

DataTable requires a value as an array of objects and columns defined with p-column component. Throughout the samples, a car interface having vin, brand, year and color properties is used to define an object to be displayed by the datatable. Cars are loaded by a CarService that connects to a server to fetch the cars with a Promise.


export interface Car {
    vin;
    year;
    brand;
    color;
}


import {Injectable} from 'angular2/core';
import {Http, Response} from 'angular2/http';
import {Car} from '../domain/car';

@Injectable()
export class CarService {

    constructor(private http: Http) {}

    getCarsSmall() {
        return this.http.get('/showcase/resources/data/cars-small.json')
                    .toPromise()
                    .then(res => <Car[]> res.json().data)
                    .then(data => { return data; });
    }
}

Following sample datatable has 4 columns and retrieves the data from a service on init.


export class DataTableDemo implements OnInit {

    cars: Car[];

    constructor(private carService: CarService) { }

    ngOnInit() {
        this.carService.getCarsSmall().then(cars => this.cars = cars);
    }
}

List of cars are bound to the value property and columns are defined using p-column component.


<p-dataTable [value]="cars">
    <p-column field="vin" header="Vin"></p-column>
    <p-column field="year" header="Year"></p-column>
    <p-column field="brand" header="Brand"></p-column>
    <p-column field="color" header="Color"></p-column>
</p-dataTable>

Column Component

Column component defines various options to specify corresponding features.

Properties

Name	Type	Default	Description
field	string	null	Property of a row data.
sortField	string	null	Property of a row data used for sorting, defaults to field.
filterField	string	null	Property of a row data used for filtering, defaults to field.
header	string	null	Header text of a column.
footer	string	null	Footer text of a column.
sortable	any	false	Defines if a column is sortable.
sortFunction	function	null	Sort function for custom sorting.
editable	boolean	false	Defines if a column is editable.
filter	boolean	false	Defines if a column can be filtered.
filterMatchMode	string	null	Defines filterMatchMode; "startsWith", "contains", "endsWith", "equals", "notEquals" and "in".
filterType	string	text	Type of the filter input field.
filterPlaceholder	string	null	Defines placeholder of the input fields.
filterMaxlength	number	null	Specifies the maximum number of characters allowed in the filter element.
excludeGlobalFilter	boolean	false	Whether to exclude from global filtering or not.
rowspan	string	null	Number of rows to span for grouping.
colspan	string	null	Number of columns to span for grouping.
style	object	null	Inline style of the column, can be override with headerStyle, bodyStyle and footerStyle.
styleClass	string	null	Style class of the column, can be override with headerStyleClass, bodyStyleClass and footerStyleClass.
exportable	boolean	true	Whether the column is included during data export.
headerStyle	object	null	Inline header style of the column.
headerStyleClass	string	null	Header style class of the column.
bodyStyle	object	null	Inline body style of the column.
bodyStyleClass	string	null	Body style class of the column.
footerStyle	object	null	Inline footer style of the column.
footerStyleClass	string	null	Footer style class of the column.
hidden	boolean	false	Controls visiblity of the column.
expander	boolean	false	Displays an icon to toggle row expansion.
selectionMode	string	null	Defines column based selection mode, options are "single" and "multiple".
frozen	boolean	false	Whether the column is fixed in horizontal scrolling or not.
scope	string	null	Scope property for screen readers, valid values are "col", "row", "colgroup" and "rowgroup".
resizable	boolean	true	Whether the column is resizable when resizableColumns is enabled at DataTable.


<p-column field="vin" header="Vin" [sortable]="true"></p-column>

Dynamic Colums

Columns can be instantiated using an array as well by iterating with ngFor.


export class DataTableDemo implements OnInit {

    cars: Car[];

    cols: any[];

    constructor(private carService: CarService) { }

    ngOnInit() {
        this.carService.getCarsSmall().then(cars => this.cars = cars);

        this.cols = [
            {field: 'vin', header: 'Vin'},
            {field: 'year', header: 'Year'},
            {field: 'brand', header: 'Brand'},
            {field: 'color', header: 'Color'}
        ];
    }
}


<p-dataTable [value]="cars">
    <p-column *ngFor="let col of cols" [field]="col.field" [header]="col.header"></p-column>
</p-dataTable>

Change Detection

DataTable either uses setter based checking or ngDoCheck to realize if the underlying data has changed to update the UI. This is configured using the immutable property, when enabled (default) setter based detection is utilized so your data changes such as adding or removing a record should always create a new array reference instead of manipulating an existing array as Angular does not trigger setters if the reference does not change. For example, use slice instead of splice when removing an item or use spread operator instead of push method when adding an item. On the other hand, setting immutable property to false removes this restriction by using ngDoCheck with IterableDiffers to listen changes without the need to create a new reference of data. Setter based method is faster however both methods can be used depending on your preference. Note that immutable property also defines how DataTable treats the data, for example when immutable is enabled sorting does not mutate the original data but creates a new array of sorted data.

Templates

Field data of a corresponding row is displayed as the cell content by default, this can be customized using templating where the implicit variable passed to the ng-template is the column definition and data of current row is the rowData property. In addition index of the current can be accessed using the optional rowIndex variable. Similarly, custom content can be placed at the header and footer of a column with templating.

A ng-template inside a column must be decorated with pTemplate directive along with the type to indicate where the ng-template belongs to. Possible values are "header", "body" and "footer".


<p-column field="color" header="Color">
    <ng-template let-col let-car="rowData" let-ri="rowIndex" pTemplate="body">
        <span>{{car[col.field]}}</span>
    </ng-template>
</p-column>
<p-column>
    <ng-template pTemplate="header">
        <button type="button" pButton (click)="selectAllCars()" icon="fa-check"></button>
    </ng-template>
    <ng-template let-car="rowData" pTemplate="body">
        <button type="button" pButton (click)="selectCar(car)" icon="fa-search"></button>
    </ng-template>
</p-column>

Index of the row is available at the ng-template.


    <p-column>
        <ng-template let-car="rowData" let-i="rowIndex" pTemplate="body">
            <button type="button" pButton (click)="selectCar(i)" icon="fa-search"></button>
        </ng-template>
    </p-column>

Name	Type	Default	Description
value	array	null	An array of objects to display.
headerRows	array	null	An array of column definitions for column grouping at header.
footerRows	array	null	An array of column definitions for column grouping at footer.
rows	number	null	Number of rows to display per page.
paginator	boolean	false	When specified as true, enables the pagination.
totalRecords	number	null	Number of total records, defaults to length of value when not defined.
pageLinks	number	null	Number of page links to display in paginator.
rowsPerPageOptions	array	null	Array of integer values to display inside rows per page dropdown of paginator
alwaysShowPaginator	boolean	true	Whether to show it even there is only one page.
sortMode	string	single	Defines whether sorting works on single column or on multiple columns.
sortField	string	null	Name of the field to sort data by default.
sortOrder	number	1	Order to sort when default sorting is enabled.
defaultSortOrder	number	1	Sort order to use when an unsorted column gets sorted by user interaction.
multiSortMeta	array	null	An array of SortMeta objects to sort the data by default in multiple sort mode.
rowGroupMode	string	null	Type of the row grouping, valid values are "subheader" and "rowspan".
groupField	string	null	Name of the field to group by in subheader row grouping mode.
sortableRowGroup	boolean	true	Whether to sort the data if the row group subheader is clicked.
expandableRowGroups	boolean	false	When enabled, adds a clickable icon at group header to expand or collapse the group.
expandedRowsGroups	array	null	Collection of group field values to show a group as expanded by default.
responsive	boolean	false	Defines if the columns should be stacked in smaller screens.
selectionMode	string	null	Specifies the selection mode, valid values are "single" and "multiple".
headerCheckboxToggleAllPages	boolean	false	When set to true, the header checkbox on paged DataTables with checkbox multiple selection enabled will toggle the selection of items across all pages. See the live example.
selection	any	null	Selected row in single mode or an array of values in multiple mode.
editable	boolean	false	Activates incell editing when enabled.
expandableRows	boolean	false	Activates expandable rows feature when true.
expandedRows	array	null	Collection of rows to display as expanded.
rowExpandMode	string	multiple	Whether multiple rows can be expanded at any time. Valid values are "multiple" and "single".
rowGroupExpandMode	string	multiple	Whether multiple row groups can be expanded at any time. Valid values are "multiple" and "single".
expandedIcon	string	fa-chevron-circle-down	Row toggler icon of an expanded row toggler.
collapsedIcon	string	fa-chevron-circle-right	Row toggler icon of a collapsed row toggler.
globalFilter	any	null	Reference of an input field to use as a global filter.
filterDelay	number	300	Delay in milliseconds before filtering the data.
lazy	boolean	false	Defines if data is loaded and interacted with in lazy manner.
resizableColumns	boolean	false	When enabled, columns can be resized using drag and drop.
columnResizeMode	string	fit	Defines whether the overall table width should change on column resize, valid values are "fit" and "expand".
reorderableColumns	boolean	false	When enabled, columns can be reordered using drag and drop.
scrollable	boolean	false	When specifies, enables horizontal and/or vertical scrolling.
scrollHeight	string	null	Height of the scroll viewport.
scrollWidth	string	null	Width of the scroll viewport.
virtualScroll	boolean	false	Whether the data should be loaded on demand during scroll.
virtualScrollDelay	number	500	Delay in virtual scroll before doing a call to lazy load.
frozenValue	array	null	A collection to display as frozen in a scrollable table.
style	string	null	Inline style of the component.
styleClass	string	null	Style class of the component.
contextMenu	ContextMenu	null	Local ng-template varilable of a ContextMenu.
csvSeparator	string	,	Character to use as the csv separator.
exportFilename	string	download	Name of the exported file.
emptyMessage	string	No records found.	Text to display when there is no data.
paginatorPosition	string	bottom	Position of the paginator, options are "top","bottom" or "both".
rowStyleClass	function	null	Function that gets the row data and row index as parameters and returns a style class for the row. This is an alternative to the rowStyleMap approach.
rowStyleMap	object	null	An object whose keys are dataKeys of rows and values are the corresponding style class of that row. This is an alternative to the rowStyleClass approach.
rowHover	boolean	false	Adds hover effect to rows without the need for selectionMode.
filters	array	null	An array of FilterMetadata objects to provide external filters.
metaKeySelection	boolean	true	Defines whether metaKey is requred or not for the selection. When true metaKey needs to be pressed to select or unselect an item and when set to false selection of each item can be toggled individually. On touch enabled devices, metaKeySelection is turned off automatically.
dataKey	string	null	A property to uniquely identify a record in data.
loading	boolean	false	Displays a loader to indicate data load is in progress.
loadingIcon	string	fa-circle-o-notch	The icon to show while indicating data load is in progress.
rowTrackBy	Function	null	Function to optimize the dom operations by delegating to ngForTrackBy, default algoritm checks for object identity.
compareSelectionBy	string	deepEquals	Algorithm to define if a row is selected, valid values are "equals" that compares by reference and "deepEquals" that compares all fields.
first	number	0	Index of the first row to be displayed. It supports two-way binding so that model value can be updated on pagination as well.
immutable	boolean	true	Defines how the data should be manipulated.
showHeaderCheckbox	boolean	true	Whether to show the header checkbox in checkbox based selection mode.

Name	Parameters	Description
onRowClick	event.originalEvent: Browser event event.data: Selected data	Callback to invoke when a row is clicked.
onRowSelect	event.originalEvent: Browser event event.data: Selected data event.type: Type of selection, valid values are "row", "radiobutton" and "checkbox"	Callback to invoke when a row is selected.
onRowUnselect	event.originalEvent: Browser event event.data: Unselected data event.type: Type of unselection, valid values are "row" and "checkbox"	Callback to invoke when a row is unselected with metakey.
onRowDblclick	event.originalEvent: Browser event event.data: Selected data	Callback to invoke when a row is selected with double clicked.
onHeaderCheckboxToggle	event.originalEvent: Browser event event.checked: State of the header checkbox	Callback to invoke when state of header checkbox changes.
onContextMenuSelect	event.originalEvent: Browser event event.data: Selected data	Callback to invoke when a row is selected with right click.
onColResize	event.element: Resized column header event.delta: Change of width in number of pixels	Callback to invoke when a column is resized.
onColReorder	event.dragIndex: Index of the dragged column event.dropIndex: Index of the dropped column event.columns: Columns array after reorder.	Callback to invoke when a column is reordered.
onLazyLoad	event.first = First row offset event.rows = Number of rows per page event.sortField = Field name to sort with event.sortOrder = Sort order as number, 1 for asc and -1 for dec filters: FilterMetadata object having field as key and filter value, filter matchMode as value	Callback to invoke when paging, sorting or filtering happens in lazy mode.
onEditInit	event.column: Column object of the cell event.data: Row data	Callback to invoke when a cell switches to edit mode.
onEdit	event.originalEvent: Browser event event.column: Column object of the cell event.data: Row data event.index: Row index	Callback to invoke when cell data is being edited.
onEditComplete	event.column: Column object of the cell event.data: Row data event.index: Row index	Callback to invoke when cell edit is completed.
onEditCancel	event.column: Column object of the cell event.data: Row data event.index: Row index	Callback to invoke when cell edit is cancelled with escape key.
onPage	event.first: Index of first record in page event.rows: Number of rows on the page	Callback to invoke when pagination occurs.
onSort	event.field: Field name of the sorted column event.order: Sort order as 1 or -1 event.multisortmeta: Sort metadata in multi sort mode. See multiple sorting section for the structure of this object.	Callback to invoke when a column gets sorted.
onFilter	event.filters: Filters object having a field as the property key and an object with value, matchMode as the property value. event.filteredValue: Filtered data after running the filtering.	Callback to invoke when data is filtered.
onRowExpand	event.originalEvent: Browser event data: Row data to expand.	Callback to invoke when a row is expanded.
onRowCollapse	event.originalEvent: Browser event data: Row data to collapse.	Callback to invoke when a row is collapsed.
onRowGroupExpand	event.originalEvent: Browser event group: Value of the group.	Callback to invoke when a row group is expanded.
onRowGroupCollapse	event.originalEvent: Browser event group: Value of the group.	Callback to invoke when a row group is collapsed.
onValueChange	value: New value.	Callback to invoke when value of table is updated.

Name	Parameters	Description
reset	-	Resets sort, filter and paginator state.
exportCSV	config?.selectionOnly: Exports only the selection.	Exports the data in csv format.
toggleRow	data	Toggles row expansion for given row data.

Name	Element
ui-datatable	Container element.
ui-datatable-header	Header section.
ui-datatable-footer	Footer section.
ui-column-title	Title of a column.
ui-sortable-column	Sortable column header.
ui-column-filter	Filter element in header.
ui-cell-data	Data cell in body.
ui-cell-editor	Input element for incell editing.
ui-datatable-scrollable-header	Container of header in a scrollable table.
ui-datatable-scrollable-body	Container of body in a scrollable table.
ui-datatable-scrollable-footer	Container of footer in a scrollable table.
ui-datatable-responsive	Container element of a responsive datatable.
ui-datatable-emptymessage	Cell containing the empty message.
ui-expanded-row	Expanded tr element.
ui-expanded-row-content	Next tr sibling of the expanded tr element.
ui-rowgroup-header	Header of a rowgroup.
ui-rowgroup-footer	Footer of a rowgroup.

Basic

Import

Getting Started

Column Component

Properties

Dynamic Colums

Change Detection

Templates

Facets

Column Grouping

Row Grouping

Paginator

Sorting

Filtering

Selection

ContextMenu

Editing

Expandable Rows

Column Resize

Column Reordering

Data Export

Scrolling

Lazy Loading

Responsive

EmptyMessage

Overlays in Cells

Loading Status

Custom Style Class per Row

Performance Tips Status

Properties

Events

Methods

Styling

Dependencies