Developer Programs

Learn

Docs

Tree Grid

Components > Displaying Data > Tree Grid
Use this component to...
Display hierarchical data with rows and columns

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.

The tree grid displays hierarchical data in rows and columns
Tree grid example

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.
The user entered “9” as the filter criteria in the Phone filter, so the grid only shows rows that contain “9” in that column
Grid filters

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
p-treeTable
Module: TreeTableModule - Package: primeng
⚠️ This component requires the use of Angular and will not work in non-Angular applications.

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
p-treeTable
Module: TreeTableModule - Package: primeng

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

Figma design info
You can find this component in the Components - Data Grids and Tables page in the Figma UI Kit.
Dev ComponentDesign Component Name
Grid rowRUI / Grid / Row
Grid column header sort button

RUI / Grid / Column Sort Button

Available values for the Sort Direction property:

  • Unsorted
  • Ascending
  • Descending
Grid row expand/collapse buttonRUI / Grid / Expand-Collapse Button
Grid 'more' buttonRUI / Grid / More Button
CheckboxRUI / 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.

Adobe XD design

Adobe XD design info
You can find this component in these artboards in the Adobe XD design samples:
  • Sample App - Grid – Grid
  • Sample App - Grid - Grid Showing Expanded Row
  • Sample App - Tree Grid
Dev ComponentDesign Component Name
Grid header rowJHA / Grid / Row; choose the “Header” state
Grid column header sort button - sorted ascendingJHA / Grid / Responsive Table Sort Button / Up
Grid column header sort button - sorted descendingJHA / Grid / Responsive Table Sort Button / Down
Grid column header sort button - unsortedJHA / Grid / Responsive Table Sort Button / Unsorted
Grid filter rowJHA / Grid / Row; choose the “Filter” state
Grid filter boxJHA / Grid / Filter Box
Grid row

JHA / Grid / Row

  • Use the First Data Row state if this is the first data row in the grid
  • Use the Contains Input state if any cell in this row contains an input or button group component.
  • Use the First Data Row Contains Input state if this is the first data row in the grid and any cell in this row contains an input or button group component.
  • Use the Default State otherwise.
Tree grid expand buttonJHA / Grid / Tree Grid Expand Button
Tree grid collapse buttonJHA / 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.
  • 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.

Support options
Have questions on this topic?
Join the Responsive UI team in Microsoft Teams to connect with the community.
See something in this page that needs to change?
Send us feedback on this page.
Last updated Wed Apr 19 2023