Grouping Guide

Setting Up Grouping

To implement grouping, provide the grouped row model to the table. The grouped row model handles row organization based on the grouping state.

import {getGroupedRowModel} from "@qualcomm-ui/core/table"

const table = useReactTable({
  // other options...
  getGroupedRowModel: getGroupedRowModel(),
})

When grouping state is active, the table adds matching rows as subRows to the grouped row. The grouped row appears in the table at the same index as the first matching row, and the matching rows are removed from the top-level table rows.

To enable expand and collapse functionality for grouped rows, add the expanding feature:

import {getGroupedRowModel, getExpandedRowModel} from "@qualcomm-ui/core/table"

const table = useReactTable({
  // other options...
  getGroupedRowModel: getGroupedRowModel(),
  getExpandedRowModel: getExpandedRowModel(),
})

Grouping State

The grouping state is an array of column ID strings that determines grouping order. The array order determines the grouping hierarchy. For example, ['column1', 'column2'] groups first by column1, then by column2 within each column1 group.

Control the grouping state using the setGrouping function:

table.setGrouping(["column1", "column2"])

Reset the grouping state to its initial state using the resetGrouping function:

table.resetGrouping()

By default, grouped columns move to the start of the table. Control this behavior using the groupedColumnMode option:

• 'reorder' - Grouped columns move to the start of the table
• 'remove' - Grouped columns are removed from the table
• false - Grouped columns remain in their original position

const table = useReactTable({
  // other options...
  groupedColumnMode: "reorder",
})

Aggregations

When rows are grouped, aggregate data in grouped rows by columns using the aggregationFn option. Specify the aggregation function ID as a string.

const column = columnHelper.accessor("key", {
  aggregationFn: "sum",
})

In the above example, the sum aggregation function aggregates data in the grouped rows. By default, numeric columns use the sum aggregation function, and non-numeric columns use the count aggregation function. Override this behavior by specifying the aggregationFn option in the column definition.

Built-in aggregation functions:

• sum - Sums the values in the grouped rows
• count - Counts the number of rows in the grouped rows
• min - Finds the minimum value in the grouped rows
• max - Finds the maximum value in the grouped rows
• extent - Finds the extent (min and max) of the values in the grouped rows
• mean - Finds the mean of the values in the grouped rows
• median - Finds the median of the values in the grouped rows
• unique - Returns an array of unique values in the grouped rows
• uniqueCount - Counts the number of unique values in the grouped rows

const table = useReactTable({
  // other options...
  aggregationFns: {
    myCustomAggregation: (columnId, leafRows, childRows) => {
      // return the aggregated value
    },
  },
})

const column = columnHelper.accessor("key", {
  aggregationFn: "myCustomAggregation",
})

Manual Grouping

For server-side grouping and aggregation, enable manual grouping using the manualGrouping option. When set to true, the table will not automatically group rows using getGroupedRowModel() and expects manually grouped rows before passing them to the table.

const table = useReactTable({
  // other options...
  manualGrouping: true,
})

Grouping Change Handler

To manage the grouping state externally, use the onGroupingChange option. This function is called when the grouping state changes. Pass the managed state back to the table via the tableOptions.state.grouping option.

const [grouping, setGrouping] = useState<string[]>([])

const table = useReactTable({
  // other options...
  state: {
    grouping: grouping,
  },
  onGroupingChange: setGrouping,
})