useLeafyGreenTable

The useLeafyGreenTable hook provides a custom integration with the @tanstack/react-table library to manage advanced table behavior such as sorting, expanding, and rendering rows dynamically. It builds on @tanstack/react-table's useReactTable hook, adding LeafyGreen-specific configurations and integrations for seamless use with LeafyGreen's Table components.

Although all react-table features are supported using LeafyGreen Table, only the following features are styled according to design system guidelines:

- Sub rows
- Expandable rows
- Selectable rows
- Sortable rows
- Sticky row header

Usage with LeafyGreen Table components:

`jsx
import {
Cell,
flexRender
HeaderCell
HeaderRow,
Row,
Table,
TableBody,
TableHead,
useLeafyGreenTable,
} from '@leafygreen-ui/table';

// Data that should be passed to the useLeafyGreenTable hook.
const [data] = useState(() => makeKitchenSinkData(200));

// Column definition
const columns = React.useMemo>>(
() => [
{
accessorKey: 'rowOne',
header: 'Row One',
},
{
accessorKey: 'rowTwo',
header: 'Row Two',
},
{
accessorKey: 'rowThree',
header: 'Row Three',
},
],
[],
);

// Table instance
const table = useLeafyGreenTable({
data,
columns,
});

// Rows returned from the table instance
const { rows } = table.getRowModel();

return (


The useLeafyGreenTable hook expects data in the form of an array of objects, where each object represents a row in the table. Each property of the object corresponds to a column in the table. Here’s a breakdown of the key requirements for the data:

#### Structure

- Rows: Each row is an object containing key-value pairs.
- Key: Corresponds to the column’s accessorKey defined in the column configuration.
- Value: The data displayed in the cell for that row and column.
Example:
`jsx
const data = [
{ id: 1, firstName: 'Alice', lastName: 'Smith', age: 30 },
{ id: 2, firstName: 'Bob', lastName: 'Johnson', age: 25 },
];
`
- SubRows: Are used to represent nested rows within a parent row. This is useful for hierarchical data where each row can have child rows. The data can include a subRows key in each object. This key holds an array of child rows for that specific row.

Example:

`jsx
const data = [
{
id: 1,
firstName: 'Alice',
lastName: 'Smith',
age: 30,
subRows: [{ id: 11, firstName: 'Anna', lastName: 'Smith', age: 5 }],
},
];
`

- ExpandedContent: Is used to display additional content when a row is expanded. This content is not necessarily a nested row but can be any additional information related to the row.

Example:

`jsx
const SampleExpandedContent = (row: LeafyGreenTableRow) => {
return (


{JSON.stringify(row.original, null, 2)}

const data = [
{
id: 1,
name: 'Parent Row',
subRows: [
{ id: 2, name: 'Child Row 1' },
{ id: 3, name: 'Child Row 2' },
],
renderExpandedContent: SampleExpandedContent,
},
];
`

#### Stable Reference

Data passed to useLeafyGreenTable MUST have a stable reference to ensure optimal performance and avoid unnecessary re-renders. Internally, useReactTable relies on reference equality for state updates. If the reference changes frequently, the hook might assume the data has been modified, triggering expensive updates. Changes to the data should explicitly signal an update. Stable references allow React to detect when actual changes occur versus unnecessary re-renders.

Example:

`jsx
const fallbackData = []

export default function MyComponent() {
//✅ GOOD: This will not cause an infinite loop of re-renders because columns is a stable reference
const columns = useMemo(() => [
// ...
], []);

//✅ GOOD: This will not cause an infinite loop of re-renders because data is a stable reference
const [data, setData] = useState(() => [
// ...
]);

// Columns and data are defined in a stable reference, will not cause infinite loop!
const table = useReactTable({
columns,
data ?? fallbackData, //also good to use a fallback array that is defined outside of the component (stable reference)
});

return

React.useState and React.useMemo are not the only ways to give your data a stable reference. You can also define your data outside of the component or use a 3rd party state management library.

The main thing to avoid is defining the data array inside the same scope as the useReactTable call. That will cause the data array to be redefined on every render, which will cause an infinite loop of re-renders.

For more information check out TanStack's docs on giving data a stable reference.

$3

The columns configuration is an array of objects, where each object defines how a column behaves and renders. It uses the @tanstack/react-table column definitions and might include:

- accessorKey: The key in the data object to use for that column.
- header: A string or function to define the column header.
- cell: A function for custom cell rendering.
- Other options like enableSorting, size, or accessorFn for computed values. Checkout TanStack's docs on column definitions for more information.
Example:
`jsx
const columns = [
{ accessorKey: 'id', header: 'ID', size: 50 },
{ accessorKey: 'firstName', header: 'First Name' },
{ accessorKey: 'lastName', header: 'Last Name' },
{ accessorKey: 'age', header: 'Age', size: 50, enableSorting: true },
];
`

$3

useLeafyGreenTable also exposes all table options used in react-table and by default, useLeafyGreenTable includes a few of those options:

`jsx
const [expanded, setExpanded] = useState < ExpandedState > {};

const table =
useReactTable <
LGTableDataType <
T >>
{
state: {
expanded,
...rest.state,
},
data,
columns,
getCoreRowModel: getCoreRowModel(),
getRowCanExpand: row => {
return !!row.original.renderExpandedContent || !!row.subRows?.length;
},
enableExpanding: true,
enableSortingRemoval: hasSortableColumns ? true : undefined,
getSubRows: row => row.subRows,
getSortedRowModel: getSortedRowModel(),
getPaginationRowModel: withPagination
? getPaginationRowModel()
: undefined,
onExpandedChange: setExpanded,
getExpandedRowModel: getLGExpandedRowModel(),
...rest,
};
`

- state: The state object for the table
- expanded: The current expanded state of the rows.
- getCoreRowModel: returns a basic row model that is just a 1:1 mapping of the original data passed to the table.
- getSortedRowModel: returns a row model that has had sorting applied to it.
- getPaginationRowModel: returns a row model that only includes the rows that should be displayed on the current page based on the pagination state.
- getExpandedRowModel: returns a custom row model that accounts for expandedContent and sub-rows.
- getRowCanExpand: override the default behavior of determining whether a row can be expanded.
- enableExpanding: enable expanding of all rows
- enableSortingRemoval: control the ability to remove sorting from a column
- getSubRows: used to access the sub rows for any given row
- onExpandedChange: called when the expanded table state changes

For other optional options check out the useLeafyGreenTable prop table below.

$3

The useLeafyGreenTable hook returns an object that extends the Table object from react-table with additional properties specific to LeafyGreen:

- getRowModel: Returns the an array with all rows, in addition to expanded subrows and expanded content. Subrows and expandedContent that are not expanded are not returned.
- hasSelectableRows: A boolean indicating whether the table has selectable rows.
- For more methods and properties available on the table object, refer to TanStack's table API documentation.

useLeafyGreenVirtualTable

The useLeafyGreenVirtualTable hook integrates virtualization into the LeafyGreen table by combining useVirtualizer from @tanstack/react-virtual with useLeafyGreenTable. It processes table data while optimizing rendering for large datasets by rendering only visible rows.

The primary differences between useLeafyGreenTable and useLeafyGreenVirtualTable include the following:

- Extension of Base Hook: useLeafyGreenVirtualTable builds on useLeafyGreenTable to include virtual scrolling.
- Efficient Rendering: Utilizes the @tanstack/react-virtual library for optimized rendering of large datasets.
- Container Reference: Requires a containerRef for the scrolling container.
- Virtual Properties: Adds a virtual object to the returned table model, exposing properties and methods from the virtualizer for managing virtualized rows.

The options passed to useLeafyGreenVirtualTable are the same as those passed to useLeafyGreenTable, with the addition of properties specific to virtualization, such as a required containerRef and optional virtualizer configuration options from Tanstack Virtual.

Usage with LeafyGreen Table components:

`jsx
import {
Cell,
flexRender
HeaderCell
HeaderRow,
Row,
Table,
TableBody,
TableHead,
useLeafyGreenVirtualTable,
} from '@leafygreen-ui/table';

const tableContainerRef = React.useRef(null);
const [data] = useState(() => makeKitchenSinkData(10_000));

const virtualScrollingContainerHeight = css
height: calc(100vh - 200px);
;

const columns = React.useMemo>>(
() => [
{
accessorKey: 'rowOne',
header: 'Row One',
},
{
accessorKey: 'rowTwo',
header: 'Row Two',
},
{
accessorKey: 'rowThree',
header: 'Row Three',
},
],
[],
);

const table = useLeafyGreenVirtualTable({
containerRef: tableContainerRef,
data,
columns,
virtualizerOptions: {
estimateSize: () => 50,
overscan: 10,
}
});

return (
table={table}
ref={tableContainerRef}
className={virtualScrollingContainerHeight}
>

{table
.getHeaderGroups()
.map((headerGroup: HeaderGroup) => (

{headerGroup.headers.map((header, index) => {
return (
key={header.id}
header={header}
>
{flexRender(
header.column.columnDef.header,
header.getContext(),
)}

);
})}

))}


{table.virtual.getVirtualItems() &&
table.virtual
.getVirtualItems()
.map(
(
virtualRow: LeafyGreenVirtualItem,
index: number,
) => {
const row = virtualRow.row;
const isExpandedContent = row.isExpandedContent ?? false;

return (

{!isExpandedContent && (
// row and virtualRow is required
row={row}
virtualRow={virtualRow}
data-row-index={index}
>
{row
.getVisibleCells()
.map((cell: LeafyGreenTableCell) => {
return (
// cell is required

{flexRender(
cell.column.columnDef.cell,
cell.getContext(),
)}

);
})}

)}
{isExpandedContent && (

)}

);
},
)}


)
`

$3

By default, useLeafyGreenVirtualTable passes the following defaults to the useVirtulizer hook:

`jsx
const table = useLeafyGreenTable({
...rest,
});

const { rows } = table.getRowModel();

const _virtualizer = useVirtualizer({
count: rows.length,
getScrollElement: () => containerRef.current,
estimateSize: () => 40,
overscan: 20,
...virtualizerOptions,
});
`

- count: The total number of items to virtualize.
- getScrollElement: A function that returns the scrollable element for the virtualizer. It may return null if the element is not available yet.
- estimateSize: This function is passed the index of each item and should return the actual size (or estimated size if you will be dynamically measuring items with virtualItem.measureElement) for each item. This measurement should return either the width or height depending on the orientation of your virtualizer.
- overscan: The number of items to render above and below the visible area. Increasing this number will increase the amount of time it takes to render the virtualizer, but might decrease the likelihood of seeing slow-rendering blank items at the top and bottom of the virtualizer when scrolling.

You can override any of these defaults in the useLeafyGreenVirtualTable hook with any of these options from TanStack's virtualizer options docs.

$3

The useLeafyGreenVirtualTable hook returns an object that extends the useLeafyGreenTable object with additional properties for virtual scrolling:

- virtual: An object containing properties and methods from the virtualizer instance, including a custom getVirtualItems method that maps virtual items to rows.
- getVirtualItems: used to retrieve the virtualized items, mapping them to the corresponding rows in the table. This method ensures that only the visible rows are rendered, which improves performance when dealing with large datasets.
- For more methods and properties available on the virtualizer instance, refer to TanStack's virtualizer instance docs.

Rendering Headers

Headers are returned from the useLeafyGreenTable and useLeafyGreenVirtualTable instances with the getHeaderGroups() function. The getHeaderGroups function is used to retrieve all header groups for a table. It returns an array of HeaderGroup objects. For more information, check out Tanstack's documentation on HeaderGroups.

Example:

`jsx
const table = useLeafyGreenTable({
data,
columns,
});

return(
...

{table.getHeaderGroups().map((headerGroup: HeaderGroup) => (

{headerGroup.headers.map((header, index) => {
return (

{flexRender(header.column.columnDef.header, header.getContext())}

);
})}

))}

...
)
`

Rendering Rows

Rows returned from the useLeafyGreenTable and useLeafyGreenVirtualTable instances differ slightly:

$3

$3

Rows are accessed from the table object using the getRowModel method. In this case, the returned rows array includes only visible rows. Subrows that are not visible are excluded, but if a row is expanded, its corresponding subrows are included in the array. For more information on getRowModel check out TanStack's documentation on row models.

Example:

`jsx
const table = useLeafyGreenTable({
data,
columns,
});

// Destructured from the row model and used to render the table body.
const { rows } = table.getRowModel();

return(
...

{rows.map((row: LeafyGreenTableRow) => {
return (
// row is required

{row.getVisibleCells().map(cell => {
return (
// cell is required

{flexRender(cell.column.columnDef.cell, cell.getContext())}

);
})}

);
})}

...
)
`

$3

In a virtual table, rows are retrieved using the getVirtualItems method from the virtual property of the table object.

Example:

`jsx
const table =
useLeafyGreenVirtualTable <
Person >
{
containerRef: tableContainerRef,
data,
columns,
};

const virtualItems = table.virtual.getVirtualItems();


{virtualItems &&
virtualItems.map((virtualRow: LeafyGreenVirtualItem) => {
const row = virtualRow.row;
const cells = row.getVisibleCells();
return (
// row and virtualRow is required

{cells.map((cell: LeafyGreenTableCell) => {
return (
// cell is required

{flexRender(cell.column.columnDef.cell, cell.getContext())}

);
})}

);
})}
;
`

$3

$3

Similar to the example above, rows are accessed from the table object using the getRowModel method. However, when expanded content is included in the rows returned form the getRowModel method, rows needs to be conditionally rendered:

- For each row, the isExpandedContent property is checked to determine if the row is an expanded content row.
- If isExpandedContent is false, the row is rendered normally with its visible cells.
- If isExpandedContent is true, the ExpandedContent component is rendered, passing the row as a prop.

Example:

`jsx
const table =
useLeafyGreenTable <
any >
{
data,
columns,
};

// Destructured from the row model and used to render the table body.
const { rows } = table.getRowModel();


{rows.map((row: LeafyGreenTableRow) => {
// Expanded content check
const isExpandedContent = row.isExpandedContent ?? false;

return (

{!isExpandedContent && (
// row is required

{row.getVisibleCells().map(cell => {
return (
// cell is required

{flexRender(cell.column.columnDef.cell, cell.getContext())}

);
})}

)}
// row is required
{isExpandedContent && }

);
})}
;
`

$3

Similar to the useLeafyGreenTable example above except in a virtual table, rows are retrieved using the getVirtualItems method from the virtual property of the table object.

Example:

`jsx
const table =
useLeafyGreenVirtualTable <
Person >
{
containerRef: tableContainerRef,
data,
columns,
};

// Virtual rows
const virtualItems = table.virtual.getVirtualItems();


{virtualItems &&
virtualItems.map((virtualRow: LeafyGreenVirtualItem) => {
const row = virtualRow.row;
// Expanded content check
const isExpandedContent = row.isExpandedContent ?? false;

return (
// note: the key should be virtualRow.key not row.id

{!isExpandedContent && (
// row and virtualRow is required

{row
.getVisibleCells()
.map((cell: LeafyGreenTableCell) => {
return (

{flexRender(
cell.column.columnDef.cell,
cell.getContext(),
)}

);
})}

)}
{isExpandedContent && (
// row and virtualRow is required

)}

);
})}
;
`

$3

Since rows and expanded subrows are returned in the same hierarchy within the row object, a depth check is often necessary to distinguish whether a row is a subrow. This can typically be done using the depth property included in the row object, which indicates its nesting level within the hierarchy. If the depth is greater than 0, then it is a subrow.

`jsx

{rows.map((row: LeafyGreenTableRow) => {
const isExpandedContent = row.isExpandedContent ?? false;
// depth check
const depth = row.depth ?? 0;

return (

{!isExpandedContent && (
// row is required
// Different styling for a subrow
row={row}
className={cx(css
background: ${depth === 1 ? 'white' : 'whitesmoke'};
)}
>
{row.getVisibleCells().map(cell => {
return (
// cell is required

{flexRender(cell.column.columnDef.cell, cell.getContext())}
// Additional text for a subrow
{depth === 1 && 'Subrow'}

);
})}

)}
// row is required
{isExpandedContent && }

);
})}

`

Sorting

Sorting can be applied within the column definitions:

`jsx
const columns = [
{
header: () => 'Name',
accessorKey: 'name',
sortingFn: 'alphanumeric', // use built-in sorting function by name
},
{
header: () => 'Age',
accessorKey: 'age',
sortingFn: 'myCustomSortingFn', // use custom global sorting function
},
{
header: () => 'Birthday',
accessorKey: 'birthday',
sortingFn: 'datetime', // recommended for date columns
},
{
header: () => 'Profile',
accessorKey: 'profile',
// use custom sorting function directly
sortingFn: (rowA, rowB, columnId) => {
return rowA.original.someProperty - rowB.original.someProperty;
},
},
{
header: () => 'Color',
accessorKey: 'color',
sortDescFirst: true, //sort by color in descending order first (default is ascending for string columns)
},
];
`

Be default, sorting is disabled, but you can enable sorting by setting enableSorting: true.

`jsx
{
accessorKey: 'mdbVersion',
header: 'MongoDB Version',
enableSorting: true,
size: 90,
},
`

For more information on sorting, check out TanStack's documentation on sorting.

Table Layout

By default, LeafyGreen Table uses table-layout: auto. This CSS property sets the algorithm used to lay out 

You can specify column widths using the size property in your column definitions:

`jsx
const columns = [
{
accessorKey: 'col1',
size: 270, //set column size for this column
},
//...
];
`

The width is applied to the corresponding