Tree Grid

A lightning:treeGrid component displays hierarchical data in a table. Its appearance resembles lightning:datatable, with the exception that each row can be expanded to reveal a nested group of items. Rows that contain nested data display a chevron icon to denote that they can be expanded or collapsed. This visual representation is useful for displaying structured data such as account hierarchy or forecasting data. Each column can be displayed based on the data type. For example, a phone number is displayed as a hyperlink with the tel: URL scheme by specifying the phone type. The default type is text.

This component implements styling from trees in the Lightning Design System.

These lightning:datatable features aren't available on lightning:treeGrid.

• Infinite scrolling
• Inline editing
• Passing in a fixed width value to a column
• Specifying the maximum number of rows that can be selected
• Handling of resize when a column is resized

Supported features include:

• Displaying and formatting of columns with appropriate data types
• Header-level actions
• Row-level actions
• Resizing of columns
• Selecting of rows
• Sorting of columns by ascending and descending order
• Text wrapping and clipping
• Row numbering column
• Cell content alignment

This component provides styling for up to 20 nested levels. For tree grids that require more than 20 nested levels, build your own component.

A checkbox is displayed by default in the first column. Set the hideCheckboxColumn attribute to true to remove the checkbox.

Initialize your data using the data, columns, and keyField attributes via the init handler. This example creates a table with 5 columns, where the first column displays a checkbox for row selection. Selecting the checkbox enables you to select the entire row of data and triggers the onrowselection event handler. The expandedRows attribute is optional, which expands nested items on a row when provided. Selecting a row using the checkbox does not select the rows nested below it.

The client-side controller creates selectable rows with or without nested data. The Account Owner column displays labels with an associated URL. Nested items must be defined using the _children key.

To retrieve which rows are currently expanded, use the getCurrentExpandedRows() method.

Additionally, you can toggle nested items using expandAll() and collapseAll(). For example, you want to expand all nested items.

The tree grid can be used to display accounts with contacts as nested items. Create an Apex controller that queries the fields you want to display. In this case, the controller returns the contacts for each account.

Wire this up to your component via the controller attribute. Make sure keyField is set to Id since this is the unique identifier for accounts.

The client-side controller defines the columns and calls a helper function to load the accounts and contact data.

The helper function calls the Apex controller to query record data and set the response data on the gridData attribute.

The table displays two columns, Account Name and Phone. Accounts with contacts are displayed with a chevron to denote that they can be expanded to reveal those contacts.

Use the following column properties to customize your data.

The table determines the format based on the type you specify. Each data type is associated to a base Lightning component. For example, specifying the text type renders the associated data using a lightning:formattedText component. Some of these types allow you to pass in the attributes via the typeAttributes property to customize your output.

The first data column in the table supports the following data types.

All other columns support the following data types.

To customize the formatting based on the data type, pass in the attributes for the corresponding base Lightning component. For example, pass in a custom currencyCode value to override the default currency code.

When using currency or date and time types, the default user locale is used when no locale formatting is provided. For more information on attributes, see the corresponding component documentation.

To append an icon to your data output, use the cellAttributes property to pass in these attributes.

You can add an icon with or without a label. This example defines two columns with icons. The first column specifies the utility:event icon for all rows using the iconName cell attribute, and the icon displays to the left of the data without a label. The second column uses computed values for the iconName and iconLabel and displays the icon to right of the data.

Header-level actions refer to tasks you can perform on a column of data, while row-level actions refer to tasks you can perform on a row of data, such as updating or deleting the row. Creating actions in lightning:treeGrid is similar to creating actions in lightning:datatable. For more information, see the lightning:datatable documentation.

If you have a large number of nested items that would delay the loading of your data, consider loading your nested items asynchronously. The nested items are displayed only when you expand the particular row. To do so, initialize your data without nested items.

Define the nested items separately.

Handle asynchronous loading of nested items when a row is expanded using the ontoggle action. Find the name of the row being expanded and check if data for the nested items is already available before retrieving and displaying the nested items.

The ontoggle action returns these parameters.

The width and height of the tree grid is determined by the container element. A scroller is appended to the tree grid body if there are more rows to display. For example, you can restrict the height to 300px by applying CSS styling to the container element.

By default, columns are resizable. Users can click and drag the width to a minimum of 50px and a maximum of 1000px. Users can also resize the column width using the keyboard. For more information, see the Accessibility section.

Working with Column Widths

You can customize the column widths in many ways. To specify your own width and disable resizing for a specific column, pass in fixedWidth to the column property. To specify an initial width and enable resizing for a specific column, pass in initialWidth to the column property.

Columns have a default minimum width of 50px and maximum width of 1000px. To change the minimum and maximum width of columns, use the minColumnWidth and maxColumnWidth attributes. For example, if you want a user to be able to resize a column to a minimum of 80px, set minColumnWidth="80".

To prevent users from resizing columns, specify resizeColumnDisabled in our markup. The table can still adjust its column widths when you resize the browser window or the width of the parent container changes.

lightning:treeGrid doesn't support the resize event. and the fixedWidth column property.

The columnWidthsMode attribute accepts values of fixed (default) or auto. To provide granular control on your column widths, use this attribute with the initialWidth column property.

Widths for the following columns are fixed and cannot be changed.

• Row Number column
• Selection (checkbox) column
• Action column

Render columns with equal widths using columnWidthsMode="fixed", which is the default setting. Any content that's too long to be displayed is clipped and appears with a trailing ellipsis. The column width is calculated by taking total available width and dividing equally among the columns.

You can specify your own widths using initialWidth only. The widths of the remaining columns without a specified initialWidth are equal.

Setting new data on the columns doesn't trigger resizing for columns, unless the new column definition specifies a change in initialWidth values. In fixed mode, the columns automatically resize and maintain equal widths when:

• The browser window is resized
• The parent container width for the datatable is changed
• The rowNumberOffset value is changed
• More or less data is passed in

When you manually resize a column to a larger width, the other columns maintain their widths, displaying a scrollbar to enable scrolling to the end of the table columns. When you manually resize to a smaller width, the other columns also maintain their widths.

You can resize manually using a mouse or a keyboard. On a keyboard, press enter in the header cell, tab to reach the resizer (column divider), and press the left or right arrow keys. On a touchscreen device, tap on the desired column resizer area, move to the desired width, and then release.

To trigger resizing of columns according to the length or size of data in a column, set columnWidthsMode="auto". In auto width mode, the columns automatically resize when:

• Data changes in at least one row and the number of rows stays the same
• The column definition changes, such as a change in a column property or the number of columns

Pass a new reference of columns with changes for resize to take effect. The columns don't resize if there's only a change in the number of records in the data.

Column widths are calculated based on the width of the content displayed in the column and the total width of the table. Specify your own widths for particular columns using the initialWidth property. The widths of the columns without the initialWidth property are calculated based on the width of the content in the column and the remaining table width. If the columns definition is passed but no data is set yet, the columns are rendered based on the width of the column labels.

A column's width is limited by the maxColumnWidth value, or 1000px by default. If a column width is calculated to be wider than the maxColumnWidth value, the content is truncated and displayed with an ellipsis. If the column also specifies wrapText: true, the column results in a narrower width than if the column has clipped text.

A column's width is also limited by the minColumnWidth value, or 50px by default. If a column width is calculated to be narrower than the minColumnWidth value, the width is set to minimum column width and may have extra white space.

When you manually resize a column, the other columns maintain their widths. This behavior also occurs when a column is manually resized in fixed mode.

The columns keep their width ratios while adjusting the column widths when:

• The browser window is resized
• The parent container width for the datatable is changed
• The rowNumberOffset value is changed

Auto width mode is supported for containers with block display, which corresponds to the display: block CSS property. This component doesn't fully support containers with display:inline-block or flex properties.

The selectedRows attribute enables you to preselect rows.

To select a row programmatically, pass in the row keyField value.

The maxRowSelection attribute is currently not supported.

Use the disabledRows attribute to prevent users from changing the selection status of specified rows. Pass row identifiers into disabledRows to prevent the rows from being selected. Pass row identifiers into both disabledRows and selectedRows to prevent the rows from being deselected.

To disable a row programmatically, pass in the row keyField value to the disabledRows attribute.

To enable sorting of row data by a column label, set sortable to true for the column on which you want to enable sorting. Clicking a column header sorts rows by ascending order, and clicking it subsequently reverses the order. Handle the onsort event handler to update the table with the new column index and sort direction.

For more information, see the lightning:datatable documentation.

You can wrap or clip text within columns, which either expands the rows to reveal more content or truncates the content to a single line within the column.

To toggle between the two views, select Wrap text or Clip text from the dropdown menu on the column header.

If the number of characters is more than what the column width can display, content is clipped by default. Text wrapping is supported only for the following data types.

• currency
• date
• email
• location
• number
• percent
• phone
• text
• url

For text data type, text clipping converts newline characters to spaces and condenses multiple spaces or tabs to one space. Text clipping suppresses line breaks, truncates content to fit a single line in the column, and adds a trailing ellipsis. Text wrapping breaks lines and hyphenates words as needed to fit the column.

To enable text wrapping by default, set wrapText to true on the columns property.

Setting the maximum number of lines to display with text wrapping is currently not supported. Handling the header action event is currently not supported.

lightning:treeGrid renders a <table>with a treegrid role and an assertive live region that announces whether the table is in navigation mode or action mode. The label toggles the action mode when you press the Enter key or Space Bar on a cell. It toggles back to navigation mode when you press the Esc key to return focus to the cell. The component also announces the width of the a column during a resize.

Each row header renders with an ariaLabel attribute with the labels you provide for the column definition. By default, the row number column renders with aria-label="Row Number" and cannot be changed. When row selection is enabled, each row renders with aria-selected set to true or false depending on whether the row is selected. Each cell renders with a gridcell role.

Provide an Accessible Label for the Table

Use the ariaLabel attribute to provide a more descriptive label for the datatable for assistive technology. The label is passed down to the rendered table element as the aria-label attribute. On pages with multiple tables, ariaLabel helps users identify which table they're accessing.

Set a descriptive text value to the ariaLabel attribute on lightning:treeGrid.

Change the ARIA label dynamically.

The aria-label attribute doesn't support empty strings. If you set ariaLabel="", the table's aria-label attribute is hidden, not rendered with an empty string. An empty label string can confuse screen readers.

Although lightning:treeGrid implements lightning:datatable internally, there are differences in how keyboard navigation works. Consider these navigation guidelines.

• Tab to place focus on the tree grid. The first time you focus on the tree grid, the focus is placed on the first data row.
• When focus is on the entire data row, the row displays with a dark border across all the data cells in that row.
• To navigate between cells on the data row, use the Right and Left Arrow keys.
• To navigate between rows, use the Up and Down Arrow keys.
• To select a row using the checkbox column, navigate to the row first. Then, use the Right and Left Arrow keys to get to the checkbox column. To select the checkbox when focus is on the checkbox column, press the Space key.

• When focus is on the entire data row, use the Right and Left Arrow keys.
• When focus is on a data cell with a chevron, press Enter or the Spacebar to activate the chevron. Press Enter or the Spacebar again to expand or collapse the row.

When focus is on the entire data row, pressing Enter or the Spacebar has no effect on navigation or interaction.

When focus is on a cell that contains a link, press Enter to activate the link. If the link is a URL, the browser directs you to the website. If the link is a phone number or email, your browser prompts you to open the appropriate app for the link.

To resize a column, navigate to the header column using the arrow keys first. Use any combination of Up, Down, Left, and Right keys.

• Tab to place focus on the tree grid.
• To navigate between columns, use the Right and Left Arrow keys.
• To navigate to a header column, use the Up Arrow key.

Then, press the Enter key to activate the column header. Use the Right Arrow key to get to the column divider. To resize a column, you can increase or decrease its width using one of the following key combinations.

• Right and Left Arrow keys
• Up and Down Arrow keys
• Page Up and Page Down keys

When you resize a column, the new column width is announced by assistive technology. To finish resizing the column and return to navigation mode, press the Esc key.