RowExpander
Feature

Enables expanding of Grid rows by either row click or double click, or by adding a separate Grid column which renders a button that expands or collapses the row.

The content of the expanded row body is rendered by providing either a renderer function to the rowExpander feature config:

new Grid({
   features : {
       rowExpander : {
           renderer({record, region, expanderElement}){
               return htmlToBeExpanded;
           }
       }
   }
});

Or a widget configuration object:

new Grid({
   features : {
       rowExpander : {
           widget : {
               type : 'detailGrid',
           },
           dataField : 'orderDetails'
       }
   }
});

Note that if used in a Gantt, the Gantt's fixedRowHeight must be set to false.

This feature is disabled by default

Keyboard shortcuts

This feature has the following default keyboard shortcuts:

Keys	Action	Action description
`Shift`+`ArrowRight`	expandByKey	Expands the focused row
`Shift`+`ArrowLeft`	collapseByKey	Collapses the focused row
`Space`	toggleExpandByKey	Toggles expand/collapse when focused on the expander cell

Please note that Ctrl is the equivalent to Command and Alt is the equivalent to Option for Mac users

For more information on how to customize keyboard shortcuts, please see our guide

Expand on click

Set triggerEvent to a Grid cell event that should trigger row expanding and collapsing.

new Grid({
   features : {
       rowExpander : {
           triggerEvent: 'celldblclick',
           renderer...
       }
   }
});

Expander column position

The expander column can either be inserted before or after the existing Grid columns. If the Grid has multiple regions the column will be added to the first region.

Adjust expander column position to last in a specific Grid region by setting columnPosition to last and configuring the column with a region name.

new Grid({
   features : {
       rowExpander : {
           column: {
               region: 'last'
           },
           columnPosition: 'last',
           renderer...
       }
   }
});

Record update

If the expander content depends on row record data, the expander can be re-rendered on record update by setting refreshOnRecordChange to true.

new Grid({
   features : {
       rowExpander : {
           refreshOnRecordChange: true,
           renderer...
       }
   }
});

Async

When the content of the row expander should be rendered async just see to it that you return a promise.

new Grid({
   features : {
       rowExpander : {
           async renderer({record, region, expanderElement}){
               return fetchFromBackendAndRenderData(record);
           }
       }
   }
});

Multiple regions

When the Grid has more than one region, the renderer function will be called once per region for each expanding row.

new Grid({
   features : {
       rowExpander : {
           renderer({ record, region }) {
               if(region === 'locked') {
                   return createRowExpander(record);
               }

               return null;
           }
       }
   }
});

If you are using the widget configuration, you can provide a widget configuration object for each region like so:

new Grid({
   features : {
       rowExpander : {
           widget : {
               locked : {
                   type : 'detailGrid',
                   // If your widgets uses different data sources, put the
                   // dataField property in the widget configuration object
                   dataField : 'orderDetails'
               },
               normal : {
                   type : 'summaryGrid',
                   dataField : 'sumDetails'
               }
           }
       }
   }
});

This live demo has a set of buttons in the locked region and a detail grid in the normal region:

If you want your expanded content to span over all Grid regions, set the spanRegions config to true.

Configs

Configs are options you supply in a configuration object when creating an instance of this class

autoScroll : Booleanfalse

When expanding a row and the expanded body element is not completely in view, setting this to true will automatically scroll the expanded row into view.

column : ActionColumnConfig/ActionColumn

Provide a column config object to display a button with expand/collapse functionality. Shown by default, set to null to not include.

new Grid({
   features : {
       rowExpander : {
           column: {
               // Use column config options here
               region: 'last'
           }
       }
   }
});

columnPosition : 'first'/'last'first

Makes the expand/collapse button column appear either as the first column (default or first) or as the last (set to last). Note that the column by default will be added to the first region, if the Grid has multiple regions. Use the column config to change region.
dataField : String

Used together with widget to populate the widget's Store from the expanded record's corresponding dataField value, which needs to be an array of objects or a store itself.
enableAnimations : Booleantrue

Use this to disable expand and collapse animations.
keyMap : Object<String, KeyMapConfig>

See Keyboard shortcuts for details
loadingIndicatorHeight : Number

Use this for customizing async renderer loading indicator height.
loadingIndicatorText : StringLoading

Use this for customizing async renderer loading indicator text.
refreshOnRecordChange : Booleanfalse

If set to true, the RowExpander will, on record update, re-render an expanded row by calling the renderer function or recreate the configured widget.
spanRegions : Booleanfalse

When the Grid has multiple regions, setting this config to true changes how the expanded content is created and rendered. Instead of calling renderer once per region (or one widget per region) it will only create one expanded element which will span the full grid width regardless of Grid regions.
triggerEvent : String
The name of the Grid event that will toggle expander. Defaults to null but can be set to any event such as cellDblClick or cellClick.
```
features : {
    rowExpander : {
        triggerEvent : 'cellclick'
    }
}
```

widget : WidgetConfig/Object<String, WidgetConfig>

A widget configuration object that will be used to create a widget to render into the row expander body. Can be used instead of providing a renderer.

If the widget needs a store, it can be populated by use of the dataField config. This will create a store from the expanded record's corresponding dataField value, which needs to be an array of objects or a store itself.

new Grid({
   features : {
       rowExpander : {
           widget : {
               type : 'detailGrid',
           },
           dataField : 'orderDetails'
       }
   }
});

If there is multiple regions, you can configure each region like so:

new Grid({
    features : {
        rowExpander : {
            widget : {
                // The region name is the property, and its widget config the value
                left : {
                   type : 'detailGrid',
                   // If your widgets uses different data sources, put the dataField
                   //  property in the widget configuration object
                   dataField : 'orderDetails'
               },
               middle : {
                   type : 'summaryGrid',
                   dataField : 'sumDetails
               },
               // No expander here
               right : null
            }
        }
    }
})

Please note that usage of this config requires access to the Shadow DOM. If your app lives in a sandboxed environment with restrictions on Shadow DOM manipulation, this is not supported. Known example of such environment is the SalesForce Lightning Web Components running without Lightning Web Security enabled.

renderer : Function

ASYNC

The implementation of this function is called each time the body of an expanded row is rendered. Either return an HTML string, a DomConfig object describing the markup or any Widget configuration object, like a Grid configuration object for example.

You should never modify any records inside this method.

new Grid({
   features : {
       rowExpander : {
           renderer({record, region, expanderElement}){
               return htmlToBeExpanded;
           }
       }
   }
});

Or return a DomConfig object.

new Grid({
   features : {
       rowExpander : {
           renderer({record, region, expanderElement}){
               return {
                  tag       : 'form',
                  className : 'expanded-row-form',
                  children  : [
                      {
                          tag        : 'textarea',
                          name       : 'description',
                          className  : 'expanded-textarea'
                      },
                      {
                          tag        : 'button',
                          text       : 'Save',
                          className  : 'expanded-save-button',
                      }
                  ]
               };
           }
       }
   }
});

Or return a Widget configuration object. What differs a Widget configuration object from a DomConfig object is the presence of the type property and the absence of a tag property.

new Grid({
   features : {
       rowExpander : {
           async renderer({record, region, expanderElement}){
               const myData = await fetch('myURL');
               return {
                  type : 'grid',
                  autoHeight : true,
                  columns : [
                      ...
                  ],
                  data : myData
               };
           }
       }
   }
});

It is also possible to add markup directly to the expanderElement.

new Grid({
   features : {
       rowExpander : {
           renderer({record, region, expanderElement}){
               new UIComponent({
                   appendTo: expanderElement,
                   ...
               });
           }
       }
   }
});

The renderer function can also be asynchronous.

new Grid({
   features : {
       rowExpander : {
           async renderer({record, region, expanderElement}){
               return await awaitAsynchronousOperation();
           }
       }
   }
});

Please note that returning a Widget configuration object requires access to the Shadow DOM. If your app lives in a sandboxed environment with restrictions on Shadow DOM manipulation, this is not supported. Known example of such environment is the SalesForce Lightning Web Components running without Lightning Web Security enabled.

Parameters

context : Object

Renderer context data
record : Model

Record for the row
expanderElement : HTMLElement

Expander body element
rowElement : HTMLElement

Row element
region : String

Grid region name
grid : Grid

Grid instance

Returns

String/DomConfig/null

Row expander body content

Properties

Properties are getters/setters or publicly accessible variables on this class

isRowExpander : Booleantrue

READONLY

static

ADVANCED

Identifies an object as an instance of RowExpander class, or subclass thereof.

isRowExpander : Booleantrue

READONLY

ADVANCED

Identifies an object as an instance of RowExpander class, or subclass thereof.

Functions

Functions are methods available for calling on the class

collapse( record )
: Promise

ASYNC

Tells the RowExpander that the provided record should be collapsed. If the record is in view, it will be collapsed. If the record is not in view, it will simply not be expanded when rendered into view.
expand( record )
: Promise

ASYNC

Tells the RowExpander that the provided record should be expanded. If or when the record is rendered into view, the record will be expanded.

Promise will resolve when the row gets expanded. Note that this can be much later than the actual expand call, depending on response times and if current record is in view or not.
refreshRow( record )
: Promise

ASYNC

Tells the RowExpander that the provided expanded record content should be refreshed. If or when the record is rendered into view, the content will be refreshed.

Promise will resolve when the grid gets refreshed. Note that this does not mean that the provided record content has been re-rendered yet, as it could be scrolled out of view.
collapseByKey( )

private

Collapses the focused row on Shift+ArrowLeft.
expandByKey( )

private

Expands the focused row on Shift+ArrowRight.
getExpandedRecord( elementOrWidget )
: Model

Gets the corresponding expanded record from either a nested widget or an element in the expanded body.
getExpandedWidgets( record )
: Widget

Gets the expanded widget(s) for a specified record. The widget(s) will be returned as an object with region names as properties and the widgets as values.
getNavigateableColumn( grid, editabletrue, reversefalse )
: Column

private

Get the first column that is not the checkboxSelectionColumn and not the expander column.
handleExpanderBodyKeyboardNavigation( event, record, region )

private

Handles keyboard navigation when focus is within an expander body. Arrow keys navigate out of the body back to the grid rows.
toggleExpandByKey( )

private

Toggles expand/collapse when focused on the expander column cell. Only activates when the focus is on the expander column to avoid conflicts with other Space handlers.
beforeRenderRow( )

private

Hooks on before row render to render or remove row expander content depending on record state.
bufferedRenderer( record )

private

Collects a rendering call for each record, saves them in array and calls the delayed (RAF) rafRenderer function
internalRender( )

private

Re-renders the grid from the topmost record of those saved in bufferedRenderer
lockCellHeight( rowElement, cellHeight, unlock )

private

Called when row is expanded. This function locks all cell's height to current height (before expanding).
onStoreChange( action, source, records )

private

Listens to changes in the Grid Store. Will remove expand State data on Store removal. If the refreshOnRecordChange config is true, it will trigger a re-render of the expander.
renderExpander( record, row, recordState )

private

Creates expander element for each grid region and calls the renderer, also for each grid region.
renderRowsWithAnimation( record )

private

Called when grid rows needs to re-render, for example on expand or collapse. Activates animations on grid, and deactivates them when they are completed.
scrollRowIntoView( )

private

Scrolls expanded row into view. This function is called after rowManager has finished rendering.
toggleExpand( record )

private

Toggles expanded state.
waitForTransition( )

private

Waits for height transition on the provided rows element. Then calls provided function.
collapseRow( record )
: Promise

ASYNC

ON-OWNER

Tells the RowExpander that the provided record should be collapsed. If the record is in view, it will be collapsed. If the record is not in view, it will simply not be expanded when rendered into view.
expandRow( record )
: Promise

ASYNC

ON-OWNER

Tells the RowExpander that the provided record should be expanded. If or when the record is rendered into view, the record will be expanded.

Promise will resolve when the row gets expanded. Note that this can be much later than the actual expand call, depending on response times and if current record is in view or not.

Events

Events are triggered for certain actions in this class and can be listened for to react to those actions in your code

beforeRowCollapse

ASYNC

PREVENTABLE

ON-OWNER

This event fires before row collapse is started.

Returning false from a listener prevents the RowExpander to collapse the row.

Note that this event fires when the RowExpander toggles the row, not when the actual row expander body is rendered. Most of the time this is synchronous, but in the case of a row that is not yet rendered into view by scrolling, it can happen much later.

Note that this event is triggered on the owning widget:
beforeRowExpand

ASYNC

PREVENTABLE

ON-OWNER

This event fires before row expand is started.

Returning false from a listener prevents the RowExpander to expand the row.

Note that this event fires when the RowExpander toggles the row, not when the actual row expander body is rendered. Most of the time this is synchronous, but in the case of a row that is not yet rendered into view by scrolling, it can happen much later.

Note that this event is triggered on the owning widget:
rowCollapse

ON-OWNER

This event fires when a row has finished collapsing.

Note that this event is triggered on the owning widget:
rowExpand

ON-OWNER

This event fires when a row expand has finished expanding.

Note that this event fires when actual row expander body is rendered, and not necessarily in immediate succession of an expand action. In the case of expanding a row that is not yet rendered into view by scrolling, it can happen much later.

Note that this event is triggered on the owning widget:

Event handlers

Event handlers are callbacks called as a result of certain actions in this class

onBeforeRowCollapse

ASYNC

PREVENTABLE

ON-OWNER

This handler is called before row collapse is started.

Returning false from a listener prevents the RowExpander to collapse the row.

Note that this handler is called when the RowExpander toggles the row, not when the actual row expander body is rendered. Most of the time this is synchronous, but in the case of a row that is not yet rendered into view by scrolling, it can happen much later.

Note that this handler is called on the owning widget:
onBeforeRowExpand

ASYNC

PREVENTABLE

ON-OWNER

This handler is called before row expand is started.

Returning false from a listener prevents the RowExpander to expand the row.

Note that this handler is called when the RowExpander toggles the row, not when the actual row expander body is rendered. Most of the time this is synchronous, but in the case of a row that is not yet rendered into view by scrolling, it can happen much later.

Note that this handler is called on the owning widget:
onRowCollapse

ON-OWNER

This handler is called when a row has finished collapsing.

Note that this handler is called on the owning widget:
onRowExpand

ON-OWNER

This handler is called when a row expand has finished expanding.

Note that this handler is called when actual row expander body is rendered, and not necessarily in immediate succession of an expand action. In the case of expanding a row that is not yet rendered into view by scrolling, it can happen much later.

Note that this handler is called on the owning widget:

CSS variables

CSS variables that can be set to adjust appearance

Name	Description
--b-row-expander-background	Row expander body's background color
--b-row-expander-border-bottom-color	Row expander body's border bottom color
--b-row-expander-border-bottom-width	Row expander body's border bottom width
--b-row-expander-color	Row expander body's color
--b-row-expander-font-weight	Row expander body's font weight
--b-row-expander-padding	Row expander body's padding

RowExpander
Feature

Keyboard shortcuts

Expand on click

Expander column position

Record update

Async

Multiple regions

See also

Configs

Parameters

Returns

Properties

Functions

Events

Event handlers

CSS variables

Source path

Inheritance tree3

Mixins2

Contents

RowExpander Feature

Keyboard shortcuts

Expand on click

Expander column position

Record update

Async

Multiple regions

See also

Configs

Parameters

Returns

Properties

Functions

Events

Event handlers

CSS variables

Source path

Inheritance tree3

Mixins2

Contents

RowExpander
Feature