Data Table Group By
avonni-dd-datatable-group-by
The Avonni Data Driven Data Table Group By displays records in a data table grouped by a field.
Overview
Data Table Group By is a data-driven Lightning Web Component that displays records in a data table grouped by a field.
You provide a query whose required groupBy field names the field to group rows by; the component fetches the records, groups them, and renders a data table with collapsible group rows. On top of the standard data-table features — columns, sorting, selection, inline edit, pagination, filters, and a header — the group-by-attributes object controls empty and undefined groups, per-group row counts, and group ordering.
Use Cases
Grouped record views: Show opportunities grouped by stage or accounts by industry.
Roll-up summaries: Display per-group counts alongside the rows.
Pipeline boards: Group records by a status field for a table-based overview.
Filtered groups: Combine header filters and search with grouping.
Editable grouped tables: Capture inline edits within grouped rows.
Use Case Examples
Example 1: Accounts grouped by industry
Scenario: Group accounts by industry, showing the number of rows in each group.
Result: A data table of accounts split into collapsible groups by industry, each showing its row count.
Example 2: Grouped table with pagination and filters
Scenario: Add pagination and header filters to a grouped table.
Result: A paginated, filterable table of opportunities grouped by stage.
Specifications
Attributes
allow-row-click
If true, table rows are displayed as clickable, and clicking a row fires the rowclick event.
Boolean
false
always-display-bottom-bar
If true, the footer that displays the Save and Cancel buttons is always displayed during inline editing.
Boolean
false
columns
Array of column objects that define the table columns.
DdDatatableElementColumn[]
—
default-search-value
Default search value for the search input.
String
—
default-sort-direction
Default sort direction for the table. Valid values are asc for ascending order and desc for descending order.
String
—
disabled-selection-rows-key-value
Array of row keys for which row selection is disabled.
string[]
—
draft-values
Array of record objects containing draft values for inline editing. Each object represents a record with edited field values, where the keys are field API names and the values are the new draft values for those fields. The Id field is required.
object[]
—
enable-table-header-wrap
If true, the column headers are wrapped up to 3 lines. By default, column headers display in a single line and content is clipped if it's too wide for the column width.
Boolean
false
errors
Specifies an object containing information about cell level, row level, and table level errors. When it's set, error messages are displayed on the table accordingly.
Object
—
export-to-fields
Array of additional field API names to export when exporting data from the table. These fields will be added to the query fields.
string[]
—
filters
Array of field API names that belong to the queried object. These fields will be displayed as user filters.
string[]
—
filters-attributes
Object defining the filters-specific attributes.
DdElementFiltersAttributes
—
group-by-attributes
Object defining the group by attributes.
DdDatatableGroupByAttributes
—
header-actions
Array of actions to display at the top right of the header. On click on a header action, the headeractionclick event is fired.
DdElementAction[]
—
header-avatar
Avatar displayed at the top left of the header.
DdElementAvatar
—
header-caption
Header caption, displayed above the title.
String
—
header-help-text
If present, a help text icon is displayed next to the header title. On focus or hover on the icon, the header help text is displayed in a tooltip.
String
—
header-help-text-attributes
Object defining the help text-specific attributes.
DdElementHelpTextAttributes
—
header-show-items-selected-count
If true, displays the number of selected items in the header.
Boolean
false
header-show-sort
If true, the sort field and direction are displayed in the header. The sort is based on the value of the orderBy query parameter.
Boolean
false
header-title
Main title displayed in the header.
String
—
header-visible-actions-count
Number of header actions that appear as regular buttons. Remaining actions appear in a dropdown menu.
integer
—
hide-checkbox-column
If true, the checkbox column for row selection is hidden.
Boolean
false
hide-no-results-image
If true, the image displayed when the query returns no results is hidden.
Boolean
false
hide-no-results-message
If true, the message displayed when the query returns no results is hidden.
Boolean
false
hide-table-header
If true, the table header is hidden.
Boolean
false
items-per-page
If the pagination is enabled, number of items per page. Otherwise, number of items loaded at once.
integer
100
key-field
Required for better performance. API name of the field used as unique row identifier.
String
"Id"
max-column-width
The maximum width for all columns.
Number
1000
max-row-selection
The maximum number of rows that can be selected. Checkboxes are used for selection by default, and radio buttons are used when maxRowSelection is 1.
integer
—
min-column-width
The minimum width for all columns.
Number
50
no-results-message
The message displayed when there are no results.
String
—
pagination-attributes
Object defining the pagination-specific attributes.
DdElementPaginationAttributes
—
pill-container-attributes
Object defining the pill container-specific attributes.
DdDatatableElementPillContainerAttributes
—
query
Definition of the query to execute to get the records that will be displayed in the data table. The groupBy field is required: it specifies the API name of the field used to group the rows.
DdDatatableGroupByQuery
—
read-only
If true, the table is read-only.
Boolean
false
refresh-emp
Object describing a platform event that should be subscribed to in order to refresh the component when an event is published.
DdElementRefreshEmp
—
required
If true, at least one row must be selected for the form to be valid when the hide-checkbox-column attribute is false.
Boolean
false
resize-column-disabled
If true, column resizing is disabled.
Boolean
false
resize-step
The width in pixels to resize the column when a user presses left or right arrow.
Number
—
row-number-offset
Determines where to start counting the row number.
integer
—
search-attributes
Object defining the search-specific attributes.
DdElementSearchAttributes
—
search-fields
Array of field API names that can be used by the search box to filter the records. The fields must belong to the queried object, and they must be filterable.
string[]
—
selected-rows-key-value
Array of selected rows key field values. These represent the unique key names of rows that are currently selected in the data table. Updated automatically when rows are selected or unselected.
string[]
—
show-pagination
If true, a pagination is displayed at the bottom of the data table. If false and the data table has a height limit, the items will be loaded dynamically as the user scrolls. If false and the data table does not have a height limit, a "show more" button will be displayed at the bottom of the data table.
Boolean
false
show-pill-items-selected-count
If true, displays the number of selected item in the pill container.
Boolean
false
show-row-number-column
If true, the row numbers are shown in the first column.
Boolean
false
side-panel-attributes
Object defining the side panel-specific attributes.
DdElementSidePanelAttributes
—
suppress-bottom-bar
If true, the footer that displays the Save and Cancel buttons is hidden during inline editing.
Boolean
false
total-nb-items
Total number of records available in static mode. Set this property when you load the items yourself and want to load them progressively: the component then fires the loadmore event (when the pagination is disabled) or the pagechange event (when the pagination is enabled) so you can load the next records and update the items array. When left undefined, the provided items array is paginated on the client and these events are not fired. This property has no effect in query mode.
integer
—
wrap-text-max-lines
This value specifies the number of lines after which the content will be cut off and hidden. It must be at least 1 or more. The text in the last line is truncated and shown with an ellipsis.
integer
—
Methods
refresh
Refresh the query and the records displayed in the component.
stayOnCurrentPage
Boolean
If true, the component will refresh but stay on the current page.
validate
Validates the input of the data table. If the required attribute is set to true and no rows are selected (when the checkbox column is visible), the method returns isValid as false along with an appropriate error message. Otherwise, it returns isValid as true.
Custom Events
cancel
The event fired when the Cancel button is clicked during inline editing.
The cancel event doesn't return any parameters.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
error
The event fired when an error occurs in the component.
The error event returns the following parameters.
message
string
Message of the error.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
filter
The event fired when the user filters the records.
The filter event returns the following parameters.
value
object
Object containing the filters applied by the user. Its keys correspond to the field API names of the selected filters. The values are arrays of strings, corresponding to the values selected for the filter.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
filterloadmore
The event fired in static mode when a filter menu needs its available values. Load the distinct values of the field and pass them to the setItems callback. Required to use the filters when the data is loaded by the developer (for example with a custom Apex controller).
The filterloadmore event returns the following parameters.
name
string
API name of the filter field whose values are requested.
search
string
Text typed in the filter menu search box, used to filter the values.
setItems
function
Callback to provide the filter values. Pass an array of objects with a label and a value property.
setInfiniteLoading
function
Callback to enable or disable the filter menu infinite loading. Call setInfiniteLoading(false) once all the values are loaded.
setIsLoading
function
Callback to toggle the filter menu loading state while the values are loaded.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
headeractionclick
The event fired when a header action is clicked.
The headeractionclick event returns the following parameters.
name
string
Name of the action clicked.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
loadmore
The event fired in static mode, when the user reaches the end of the component and more records remain to load (infinite loading). It is only fired when totalNbItems is set and the pagination is disabled. Load the next records and append them to the items array.
The loadmore event returns the following parameters.
search
string
Current search value, when the search box is used. Apply it when loading the next records.
setIsLoading
function
Callback toggling the component loading state while the next records are loaded. Call setIsLoading(true) before loading the records and setIsLoading(false) once they are loaded.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
nbitemschange
The event fired when the number of items displayed in the component changes.
The nbitemschange event returns the following parameters.
value
integer
Number of items displayed in the component.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
pagechange
The event fired in static mode, when the user navigates to another page or changes the search value. It is only fired when totalNbItems is set and the pagination is enabled. Load the records of the new page (applying the search) and replace the items array.
The pagechange event returns the following parameters.
value
integer
New page number.
search
string
Current search value, when the search box is used. Apply it when loading the page records.
setIsLoading
function
Callback toggling the component loading state while the new page records are loaded. Call setIsLoading(true) before loading the records and setIsLoading(false) once they are loaded.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
rowaction
Event fired when a row action is clicked.
The rowaction event returns the following parameters.
name
string
Name of the action clicked.
item
object
Row the action belongs to, with its formatted column values.
record
object
Record corresponding to the row the action belongs to. In static mode, no record is associated and this is null.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
rowclick
Event fired when a row is clicked. Requires allow-row-click to be enabled, and is not fired when clicking an editable cell, a checkbox or an interactive cell (button, link...).
The rowclick event returns the following parameters.
item
object
Clicked row, with its formatted column values.
record
object
Record corresponding to the clicked row. In static mode, no record is associated and this is null.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
save
The event fired when the Save button is clicked during inline editing.
The save event returns the following parameters.
draftValues
object[]
Array of objects containing the draft values.
newValues
object[]
Array of objects containing the new values.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
selectrows
Event fired when the item selection is updated. If items are checked by default, this event will be fired when the query is first executed. It is also fired when items are checked or unchecked by the user.
The selectrows event returns the following parameters.
selectedRowsKeyValue
string[]
Array of row field key values, corresponding to the current selection.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
sort
Event fired when user changes the data table sorting.
The sort event returns the following parameters.
sortedBy
string
The API name of the field used for sorting.
sortedDirection
string
The sort direction. Valid values are asc and desc.
The event properties are as follows.
bubbles
false
This event does not bubble.
cancelable
false
This event has no default behavior that can be canceled. You can't call preventDefault() on this event.
composed
false
This event does not propagate outside of the component in which it was dispatched.
Styling Hooks
--avonni-dd-datatable-group-by-cell-spacing
string
0.25rem 0.5rem
--avonni-dd-datatable-group-by-footer-color-background
color
#f3f3f3
--avonni-dd-datatable-group-by-footer-color-border
color
#c9c9c9
--avonni-dd-datatable-group-by-footer-radius-border
string
—
--avonni-dd-datatable-group-by-footer-sizing-border
string
—
--avonni-dd-datatable-group-by-footer-styling-border
string
solid
--avonni-dd-datatable-group-by-header-actions-color-background
color
—
--avonni-dd-datatable-group-by-header-actions-color-background-active
color
—
--avonni-dd-datatable-group-by-header-actions-color-background-hover
color
—
--avonni-dd-datatable-group-by-header-actions-color-border
color
—
--avonni-dd-datatable-group-by-header-actions-color-border-active
color
—
--avonni-dd-datatable-group-by-header-actions-color-border-hover
color
—
--avonni-dd-datatable-group-by-header-actions-text-color
color
—
--avonni-dd-datatable-group-by-header-actions-text-color-active
color
—
--avonni-dd-datatable-group-by-header-actions-text-color-hover
color
—
--avonni-dd-datatable-group-by-header-caption-font-family
string
—
--avonni-dd-datatable-group-by-header-caption-font-size
dimension
—
--avonni-dd-datatable-group-by-header-caption-font-style
string
normal
--avonni-dd-datatable-group-by-header-caption-font-weight
number
400
--avonni-dd-datatable-group-by-header-caption-letter-spacing
string
—
--avonni-dd-datatable-group-by-header-caption-line-height
string
—
--avonni-dd-datatable-group-by-header-caption-text-color
color
#000000
--avonni-dd-datatable-group-by-header-color-background
color
—
--avonni-dd-datatable-group-by-header-color-border
color
—
--avonni-dd-datatable-group-by-header-color-border-bottom
color
#c9c9c9
--avonni-dd-datatable-group-by-header-icon-color-background
color
—
--avonni-dd-datatable-group-by-header-icon-color-foreground
color
—
--avonni-dd-datatable-group-by-header-icon-color-foreground-default
color
—
--avonni-dd-datatable-group-by-header-icon-radius-border
string
—
--avonni-dd-datatable-group-by-header-margin-block-end
dimension
—
--avonni-dd-datatable-group-by-header-radius-border
string
—
--avonni-dd-datatable-group-by-header-sizing-border
string
—
--avonni-dd-datatable-group-by-header-sizing-border-bottom
dimension
1px
--avonni-dd-datatable-group-by-header-spacing-block-end
dimension
0.75rem
--avonni-dd-datatable-group-by-header-spacing-block-start
dimension
0.75rem
--avonni-dd-datatable-group-by-header-spacing-inline-end
dimension
1rem
--avonni-dd-datatable-group-by-header-spacing-inline-start
dimension
1rem
--avonni-dd-datatable-group-by-header-styling-border
string
—
--avonni-dd-datatable-group-by-header-styling-border-bottom
string
solid
--avonni-dd-datatable-group-by-header-title-font-family
string
—
--avonni-dd-datatable-group-by-header-title-font-size
dimension
1rem
--avonni-dd-datatable-group-by-header-title-font-style
string
normal
--avonni-dd-datatable-group-by-header-title-font-weight
number
400
--avonni-dd-datatable-group-by-header-title-letter-spacing
string
—
--avonni-dd-datatable-group-by-header-title-line-height
number
1.25
--avonni-dd-datatable-group-by-header-title-text-color
color
#080707
--avonni-dd-datatable-group-by-pagination-active-button-color-background
color
#0176d3
--avonni-dd-datatable-group-by-pagination-active-button-color-background-active
color
#014486
--avonni-dd-datatable-group-by-pagination-active-button-color-background-hover
color
#014486
--avonni-dd-datatable-group-by-pagination-active-button-color-border
color
#0176d3
--avonni-dd-datatable-group-by-pagination-active-button-color-border-active
color
#014486
--avonni-dd-datatable-group-by-pagination-active-button-color-border-hover
color
#014486
--avonni-dd-datatable-group-by-pagination-active-button-text-color
color
#fff
--avonni-dd-datatable-group-by-pagination-active-button-text-color-active
color
#fff
--avonni-dd-datatable-group-by-pagination-active-button-text-color-hover
color
#fff
--avonni-dd-datatable-group-by-pagination-button-color-background
color
#fff
--avonni-dd-datatable-group-by-pagination-button-color-background-active