Tree Grid
Overview
Responsive UI offers three approaches for displaying table data (i.e. data in rows and columns):
- Responsive table: Used for simple table data, with limited functionality
- Data grid: Used for complex table data, with more sophisticated functionality for interacting with the data
- Tree grid: Used for hierarchical table data
This document describes the tree grid. Use tree grid to display hierarchical data in rows and columns.
Many grid cells are left-aligned, but it’s best to right-align currency and numeric values so the decimal points and commas line up, helping the user compare numeric values across rows.
The tree grid component includes built-in behaviors sorting and filtering.
![Tree grid example](./TreeGrid.png?v=2)
Grid Filters
Filtering allows the user to reduce the data set to only include rows that meet specific criteria. To filter a grid, the user enters specific search criteria using filter inputs at the top of the grid. The grid then hides all rows that don’t meet the specified filter criteria.
The grid and tree grid components support 5 different types of filters:
- Simple Text Filter: The user enters filter text into a simple text input. The grid only shows rows that contain that value in the filtered column. The user must manually clear the filter input’s content to remove the filter.
- Search Text Filter: The user enters filter text into a search text input. The grid only shows rows that contain that value in the filtered column. To remove the filter, the user can either press the Escape key or press an “X” button that displays within the input. This is an easier experience for the user, so we recommend using search text filters instead of text box filters.
- Select filter: The user selects a filter value from a dropdown list (i.e. an HTML “select” element). The grid only shows rows that contain that value in the filtered column. This dropdown must include an “all values” option to allow the user to remove the filter.
- p-dropdown filter: The user selects a filter value from a p-dropdown, which is a dropdown component that can display templated (formatted) values. The grid only shows rows that contain that value in the filtered column. This dropdown must include an “all values” option to allow the user to remove the filter.
- p-multiSelect filter: The user selects one or more filter values from a p-multiSelect, which is a dropdown component that allows the user to select multiple values. The grid only shows rows that contain any of the selected values in the filtered column. The user must clear the selected values in the multiselect to remove the filter.
![Grid filters](./GridFilters.png?v=2)
Grid Buttons
Use the grid button component if you need to include one or more buttons in a data grid cell. It uses minimal, lightweight formatting that fits well into a data grid cell.
Development
Web component development
Component reference
p-treeTable
Displays hierarchical data in rows and columns
View the p-treeTable reference doc
If you're adding PrimeNG to your solution for the first time, reference their setup documentation. It's important to note that the inclusion of the nova-light theme css is not necessary to work with Responsive UI. Styling for the PrimeNG components is provided by Responsive UI's theming.
Styling the Grid
Add the rui-grid-minimal
CSS class to the grid component to get the proper styling.
Most grid cells are left-aligned, but it’s best to right-align currency and numeric values so the decimal points and commas line up, helping the user compare numeric values across rows.
Also, it can be helpful to wrap a grid within a div that has overflow-x:auto
so that horizontal scrollbars display at smaller screen widths, since the data in your grid may not fit into the available width.
For more information on the p-treeTable, view the full documentation at https://primeng.org/treetable.
Angular wrapper development
Wrapper reference
p-treeTable
Displays hierarchical data in rows and columns
View the p-treeTable reference doc
If you're adding PrimeNG to your solution for the first time, reference their setup documentation. It's important to note that the inclusion of the nova-light theme css is not necessary to work with Responsive UI. Styling for the PrimeNG components is provided by Responsive UI's theming.
Styling the Grid
Add the jha-grid-minimal
CSS class to the grid component to get the proper styling.
Most grid cells are left-aligned, but it’s best to right-align currency and numeric values so the decimal points and commas line up, helping the user compare numeric values across rows.
Also, it can be helpful to wrap a grid within a div that has overflow-x:auto
so that horizontal scrollbars display at smaller screen widths, since the data in your grid may not fit into the available width.
For more information on the p-treeTable, view the full documentation at https://primeng.org/treetable.
Design
Figma design
Dev Component | Design Component Name |
---|---|
Grid row | RUI / Grid / Row |
Grid column header sort button | RUI / Grid / Column Sort Button Available values for the Sort Direction property:
|
Grid row expand/collapse button | RUI / Grid / Expand-Collapse Button |
Grid 'more' button | RUI / Grid / More Button |
Checkbox | RUI / Forms / Checkbox |
The tree grid displays hierarchical data in rows and columns.
- For the header row:
- Add a grid row component as the header background. Set its Appearance property value to “Min w/o Separator”.
- For each column header:
- For each sortable column, add a column sort button (with appropriate sort direction) as a header for each column.
- For each non-sortable column — for example columns that only display grid buttons — add a text element for the column header, apply the “rui-semibold” text style and the “rui-pacific/text-regular” color style.
- Add a checkbox in the far-left column if your use case allows the user to select grid rows.
- For data rows:
- Add a grid row component as the row background.
- Set the component’s Appearance property value to Min w/o Separator if this is the first data row in the table. This state hides the top border line in the component (something we only want to display for subsequent data rows). Otherwise set its Appearance property value to Min with Separator.
- Switch on the component’s Contains Input property if any cell in this row contains an input or button group component. This sets the row height to a value large enough to contain the input or button group.
- If the row is expandable:
- If the row is shown collapsed, add a grid row Expand-Collapse button in the far left column and switch off its Expanded property.
- If the row is shown expanded, add a grid row Expand-Collapse button in the far left column and switch on its Expanded property.
- Add a text element for each column. Apply the “rui-regular” text style and the “rui-pacific/text-regular” color style to the text element.
- For nested nodes in the tree, indent the expand/collapse button and the first column’s text by 16 pixels to the right for each level of indentation.
- Add a grid row component as the row background.
Adobe XD design
- Sample App - Grid – Grid
- Sample App - Grid - Grid Showing Expanded Row
- Sample App - Tree Grid
Dev Component | Design Component Name |
---|---|
Grid header row | JHA / Grid / Row; choose the “Header” state |
Grid column header sort button - sorted ascending | JHA / Grid / Responsive Table Sort Button / Up |
Grid column header sort button - sorted descending | JHA / Grid / Responsive Table Sort Button / Down |
Grid column header sort button - unsorted | JHA / Grid / Responsive Table Sort Button / Unsorted |
Grid filter row | JHA / Grid / Row; choose the “Filter” state |
Grid filter box | JHA / Grid / Filter Box |
Grid row | JHA / Grid / Row
|
Tree grid expand button | JHA / Grid / Tree Grid Expand Button |
Tree grid collapse button | JHA / Grid / Tree Grid Collapse Button |
The tree grid displays hierarchical data in rows and columns.
- For the header row:
- Add a grid row component with the “Header” state as the background for the header row.
- For each column header:
- For each sortable column, add a sort button (with appropriate sort direction) to a header for each column.
- For each non-sortable column — for example columns that include grid buttons — add a text element for the column header, apply the “JHA / Text / Regular” character style, then add Semibold styling for the text.
- Add a checkbox in the far-left column if your use case allows the user to select grid rows.
- For the filter row (optional):
- Add a grid row component with the “Filter” state as the background for the filter row.
- Add a grid Filter Box component for each column. Size it to fit the width of the column.
- For data rows:
- Add a grid row component as the background for the data row.
- Set the component’s state to First Data Row if this is the first data row in the grid. This state hides the top border line in the component (something we only want to display for subsequent data rows).
- Set the component’s state to Contains Input if any cell in this row contains an input or button group component. This sets the row height to a value large enough to contain the input or button group.
- Set the component’s state to First Data Row Contains Input if this is the first data row in the grid and any cell in this row contains an input or button group component. This sets the proper height and hides the top line border.
- Leave the component’s state as Default State otherwise.
- If the row is expandable:
- If the row is shown collapsed, add a grid row expand button in the far left column.
- If the row is shown expanded, add a grid row collapse button in the far left column.
- Add a text element for each data column. Apply the “JHA / Text / Regular” character style to the text element.
- Add a grid row component as the background for the data row.
- For a selected data row:
- Add a grid row component with the “Selected” state as the background for the selected row.
- If the row is expandable:
- If the row is shown collapsed, add a grid row expand button in the far left column.
- If the row is shown expanded, add a grid row collapse button in the far left column.
- Set the component’s state to “Selected”.
- If the row is expandable and is shown collapsed, add a grid row expand button in the far left column. If the row is expandable and is shown expanded, add a grid row collapse button in the far left column.
- Add a text element for each column. First apply the “JHA / Text / Regular” character style to the text element, then select the “JHA / Color / Btn / Primary / Fg” color asset to set the appropriate text color.
- If you’re adding a grid “more” button to a column in a selected row, set “Selected Row” as the button’s state.
- If you’re adding a grid icon button to a column in a selected row, first select the “Grid Button” state for the icon element, then select the “JHA / Color / Btn / Primary / Fg” color asset to set the appropriate color for the icon.