NOTE: The Advanced Table kit uses the Tanstack Table v8 under the hood to render advanced tables that allow for complex, nested data structures with expansion and sort options.
The AdvancedTable kit accepts tree data and automatically renders expansion controls for nested subrows, to any depth, based on the data it is given. In it's simplest form, the kit has two required props:
tableData accepts an array of objects as the table data. Each object is a table row, and each key:value pair within an object is a column value within that row. Nested children within a data object are automatically rendered as subrows under their parent row. Each parent row is prepended with expansion controls for toggling its nested child rows. The toggleExpansionAll button in the first column header can also be used to toggle expansion of all parent rows within the table.
For a visual of the data structure needed for tableData, see here.
columnDefinitions maps to the columns prop on the Tanstack table. Column definitions are the single most important part of building a table as they are responsible for building the underlying data model that is used for all sorting, expansion, etc. ColumnDefinitions in the AdvancedTable kit is an array of objects as seen in the code snippet below. Each object within the array has two REQUIRED items:
accessor: this is the key from your data for the value you want rendered in that columnlabel: this is what will be rendered as the column header labelThere is also one optional item that is only required if the table has nested data:
cellAccessors: This is an array of strings that represent keys from your data object. This is only required for the first column in case of nested data. If you have nested data, the AdvancedTable needs to know what to render in that first column for nested items. This array represents the nested data in the order you want it rendered.the optional loading prop takes a boolean value that can be managed using state. If loading is true, the table will display the loading skeleton and once loading is false, the table will render with the data provided.
By default, the inital row count of the loading skeleton is set to 10. If you want more control over this initial row count, the optional initialLoadingRowCount prop can be used to pass in a number. NOTE: This is only for the first render of the table, subsequent loading skeleton row count logic is handled within the kit itself.
the enableSorting prop is a boolean prop set to false by default. If true, the table will add sort logic linked to the sort button in the header. Clicking the sort button will toggle sort between ascending and descending. Currently this sort functionality is only available on the first column.
An optional prop, sortIcon allows you to customize your icon sets by passing it an array of any comma-separated pair of icon values. The first icon value will replace the kit's default icon when sort direction is desc, and the second value will replace the default icon when sort direction is asc. sortIcon also allows you to pass it a single icon as a string, in which case the icon will not toggle with the sort state. Default for this prop is ["arrow-up-short-wide", "arrow-down-short-wide"]. All strings must be valid FA icons.
sortControl is an optional prop that can be used to gain greater control over the sort state of the Advanced Table. Tanstack handles sort itself, however it does provide for a way to handle the state manually if needed. Usecases for this include needing to store the sort state so it persists on page reload, set an initial sort state, etc.
The sort state must be an object with a single key/value pair, with the key being "desc" and the value being a boolean. The default for sort directino is desc: true.
NOTE: If using expandedControl the dev is expected to manage the row level expansion state themselves, the kit itself will NOT do it by default.
expandedControl is an optional prop that can be used to gain greater control over the expansion state of the Advanced Table. Tanstack handles expansion itself, however it does provide for a way to handle the state manually if needed. Usecases for this include needing to store the expansion state so it persists on page reload, set an initial expansion state, etc.
In this example we are showing that if initial expansion state is set, it will render the table expanded according to that state.
The expanded state must be an object with key/value pairs where the key is the row id and the value is a boolean, true or false. Tanstack by default assigns row ids based on index and depth of the row as can be seen in this example. For more information on row ids, see here.
By default, the click event on the row level toggleExpansion icon simply toggles the immediate sub rows open or closed. If you want to attach further logic to that button, the optional onRowToggleClick prop can be used. This click event provides one argument that can be hooked into: the current row object. Any additional functionality provided through this onClick will be applied in addition to the default.
Similar to the row level click event, the default of the click event on the toggleExpansion buttons that render in the first column header (and the subRow Header rows if prop enabled) toggles all top level rows open and closed. If you want to attach further logic to that button, the optional onToggleExpansionClick prop can be used. This click event provides one argument that can be hooked into: the current row object. Any additional functionality provided through this onClick will be applied in addition to the default.
ToggleExpansionIcon is another optional prop that can be used to customize the icon for the toggleExpansion button. This prop takes a string value with the default set to arrows-from-line. All strings must be valid FA icons.
subRowHeaders is an optional prop that if present will add header rows at each level of the nested data. The prop takes an array of strings, each string being the text for each header row. The array of strings must be in the order in which they need to be rendered in the UI according to depth.
enableToggleExpansion is an additional optional prop that can be used in conjunction with the subRowHeaders prop. enableToggleExpansion is a string that can be 'all', 'header" or "none". If set to 'all', the toggle exapansion button will appear in the table header as well as in the subRow headers. If set to 'header' button will only appear in header and NOT in subRow headers. This is set to 'header' by default.
collapsibleTrail is an optional prop that is set to 'true' by default. If set to 'false', it will remove the trail on the left of the rows when subRows are toggled open.
The Tanstack table consumes the useReactTable hook to create the table. This hook takes an object that can contain any of the functions that the Tanstack table provides. The advancedTable's optional tableOptions can be used to pass tanstack options to the kit.
In the above example, we are using the initialState option provided by tanstack that takes sort as one of it's values. Setting it to true for the first column is reversing the sort order on first render of the table. For a complete list of possible options and how to use them, see here
This kit uses the Table kit under the hood which comes with it's own set of props. If you want to apply certain Table props to that underlying kit, you can do so by using the optional tableProps prop. This prop must be an object that contains valid Table props. For a full list of Table props, see here.
As a default, the kit assumes that the initial dataset is complete, and it renders all expansion buttons/controls based on that data; if no children are present, no expansion controls are rendered. If, however, you want to change the initial dataset to omit some or all of its children (to improve load times of a complex dataset, perhaps), and you implement a querying logic that loads children only when its parent is expanded, then you must use the inlineRowLoading prop to ensure your expansion controls are rendered even though your child data is not yet loaded. You must also pass an empty children array to any node that will have children to ensure its parent maintains its ability to expand. If this prop is called AND your data contains empty children arrays, the kit will render expansion controls on any row with empty children, and then add an inline loading state within the expanded subrow until those child row(s) are returned to the page [by your query logic].
In this code example, 2021 has an empty children array. Toggle it open to see the inline loading state. Once the correct data loads, this state will be replaced with the correct data rows.
This prop is set to false by default.
