TreeTable
TreeTable is used to display hierarchical data in tabular format.
Import #
import { TreeTableModule } from 'primeng/treetable';Basic #
TreeTable requires a collection of TreeNode instances as a value components as children for the representation.
Dynamic Columns #
Columns can be created programmatically.
Controlled #
Expansion state is controlled with expandedKeys property.
Template #
Custom content at caption, header, body and summary sections are supported via templating.
Size #
In addition to a regular treetable, alternatives with alternative sizes are available. Add p-treetable-sm class to reduce the size of treetable or p-treetable-lg to enlarge it.
Grid Lines #
Enabling showGridlines displays grid lines.
Loading #
Mask #
The loading property displays a mask layer to indicate busy state. Use the paginator to display the mask.
Skeleton #
Skeleton component can be used as a placeholder during the loading process.
Paginator #
Basic #
Pagination is enabled by adding paginator property and defining rows per page.
Template #
Paginator UI is customized using the paginatorleft and paginatorright property. Each element can also be customized further with your own UI to replace the default one, refer to the Paginator component for more information about the advanced customization options.
Sort #
Single Column #
Sorting on a column is enabled by adding the ttSortableColumn property.
Multiple Columns #
Multiple columns can be sorted by defining sortMode as multiple. This mode requires metaKey (e.g. ⌘) to be pressed when clicking a header.
Filter #
The filterMode specifies the filtering strategy, in lenient mode when the query matches a node, children of the node are not searched further as all descendants of the node are included. On the other hand, in strict mode when the query matches a node, filtering continues on all descendants. A general filled called filterGlobal is also provided to search all columns that support filtering.
Selection #
Single #
Single node selection is configured by setting selectionMode as single along with selection properties to manage the selection value binding.
By default, metaKey press (e.g. ⌘) is necessary to unselect a node however this can be configured with disabling the metaKeySelection property. In touch enabled devices this option has no effect and behavior is same as setting it to false
Multiple #
More than one node is selectable by setting selectionMode to multiple. By default in multiple selection mode, metaKey press (e.g. ⌘) is necessary to add to existing selections however this can be configured with disabling the metaKeySelection property. Note that in touch enabled devices, TreeTable always ignores metaKey.
Checkbox #
Selection of multiple nodes via checkboxes is enabled by configuring selectionMode as checkbox.
In checkbox selection mode, value binding should be a key-value pair where key (or the dataKey) is the node key and value is an object that has checked and partialChecked properties to represent the checked state of a node.
{
'0': {
partialChecked: true
},
'0-0': {
partialChecked: false,
checked: true
},
'0-0-0': {
checked: true
},
'0-0-1': {
checked: true
},
'0-0-2': {
checked: true
}
}Events #
TreeTable provides onNodeSelect and onNodeUnselect events to listen selection events.
Column Group #
Lazy Load #
Lazy mode is handy to deal with large datasets, instead of loading the entire data, small chunks of data is loaded by invoking corresponding callbacks everytime paging, sorting and filtering occurs. Sample below imitates lazy loading data from a remote datasource using an in-memory list and timeouts to mimic network connection.
Enabling the lazy property and assigning the logical number of rows to totalRecords by doing a projection query are the key elements of the implementation so that paginator displays the UI assuming there are actually records of totalRecords size although in reality they are not present on page, only the records that are displayed on the current page exist.
In addition, only the root elements should be loaded, children can be loaded on demand using onNodeExpand callback.
| Name | Size | Type |
|---|
Scroll #
Vertical #
Adding scrollable property along with a scrollHeight for the data viewport enables vertical scrolling with fixed headers.
Flexible #
Flex scroll feature makes the scrollable viewport section dynamic instead of a fixed value so that it can grow or shrink relative to the parent size of the table. Click the button below to display a maximizable Dialog where data viewport adjusts itself according to the size changes.
Horizontal #
Horizontal scrolling is enabled when the total width of columns exceeds table width.
Frozen Columns #
A column can be fixed during horizontal scrolling by enabling the frozenColumns property.
Column Resize #
Fit Mode #
Columns can be resized with drag and drop when resizableColumns is enabled. Default resize mode is fit that does not change the overall table width.
Expand Mode #
Setting columnResizeMode as expand changes the table width as well.
Scrollable #
To utilize the column resize modes with a scrollable TreeTable, a colgroup template must be defined. The default value of scrollHeight is "flex," it can also be set as a string value.
Reorder #
Order of the columns can be changed using drag and drop when reorderableColumns is present.
Column Toggle #
Column visibility based on a condition can be implemented with dynamic columns, in this sample a MultiSelect is used to manage the visible columns.
Conditional Style #
Particular rows and cells can be styled based on conditions. The ngClass receives a row data as a parameter to return a style class for a row whereas cells are customized using the body template.
Context Menu #
TreeTable has exclusive integration with contextmenu component. In order to attach a menu to a table, add ttContextMenuRow directive to the rows that can be selected with context menu, define a local template variable for the menu and bind it to the contextMenu property of the table. This enables displaying the menu whenever a row is right clicked. A separate contextMenuSelection property is used to get a hold of the right clicked row. For dynamic columns, setting ttContextMenuRowDisabled property as true disables context menu for that particular row.
Accessibility #
Screen Reader
Default role of the table is table. Header, body and footer elements use rowgroup, rows use row role, header cells have columnheader and body cells use cell roles. Sortable headers utilizer aria-sort attribute either set to "ascending" or "descending".
Row elements manage aria-expanded for state and aria-level attribute to define the hierachy by ttRow directive. Table rows and table cells should be specified by users using the aria-posinset, aria-setsize, aria-label, and aria-describedby attributes, as they are determined through templating.
When selection is enabled, ttSelectableRow directive sets aria-selected to true on a row. In checkbox mode, the built-in checkbox component use checkbox role with aria-checked state attribute.
Editable cells use custom templating so you need to manage aria roles and attributes manually if required.
Paginator is a standalone component used inside the TreeTable, refer to the paginator for more information about the accessibility features.
Sortable Headers Keyboard Support
| Key | Function |
|---|---|
| tab | Moves through the headers. |
| enter | Sorts the column. |
| space | Sorts the column. |
Keyboard Support
| Key | Function |
|---|---|
| tab | Moves focus to the first selected node when focus enters the component, if there is none then first element receives the focus. If focus is already inside the component, moves focus to the next focusable element in the page tab sequence. |
| shift + tab | Moves focus to the last selected node when focus enters the component, if there is none then first element receives the focus. If focus is already inside the component, moves focus to the previous focusable element in the page tab sequence. |
| enter | Selects the focused treenode. |
| space | Selects the focused treenode. |
| down arrow | Moves focus to the next treenode. |
| up arrow | Moves focus to the previous treenode. |
| right arrow | If node is closed, opens the node otherwise moves focus to the first child node. |
| left arrow | If node is open, closes the node otherwise moves focus to the parent node. |
