Class ApexGrid<T>

autoGenerate

// assuming autoGenerate is set to true
grid.columns = [];
grid.data = [...];
Copy

columnReordering

columns

data

dataPipelineConfiguration

Optionalediting

grid.editing = { enabled: true, mode: 'cell', trigger: 'doubleClick' };
Copy

Optionalexpansion

grid.expansion = {
  enabled: true,
  detailTemplate: ({ data }) => html`<order-summary .order=${data}></order-summary>`,
};
Copy

Optionalpagination

grid.pagination = { enabled: true, pageSize: 25 };
grid.addEventListener('pageChanged', (event) => {
  console.log('Now on page', event.detail.page, 'of', event.detail.pageCount);
});
Copy

quickFilter

Optionalselection

grid.selection = { enabled: true, mode: 'multiple', showCheckboxColumn: true };
Copy

showExport

showQuickFilter

sortConfiguration

Optionaltree

grid.tree = {
  enabled: true,
  getDataPath: (row) => row.path,    // e.g., ['Adrian'], ['Adrian', 'Bryan']
  defaultExpanded: true,
};
Copy

dataView

• get dataView(): readonly T[]

  Returns the state of the data source after sort/filter operations have been applied.

  Returns readonly T[]

displayColumns

• get displayColumns(): readonly ColumnConfiguration<T>[]

  The columns in visual render order: 'start'-pinned columns first, then unpinned columns, then 'end'-pinned columns.

  Returns readonly ColumnConfiguration<T>[]

  Remarks

  Use this when you need to iterate the columns in the same order the grid actually displays them (for example to build a column chooser). Public APIs like ApexGrid.getColumn continue to operate on the user-supplied ApexGrid.columns array.

editingCell

• get editingCell(): { columnKey: keyof T; rowIndex: number } | null

  The cell currently in edit mode, or null.

  Returns { columnKey: keyof T; rowIndex: number } | null

editingRow

• get editingRow(): number | null

  The view-relative index of the row currently in edit mode (row edit mode only), or null.

  Returns number | null

expandedRows

• get expandedRows(): T[]

  The currently expanded rows, in insertion order.

  Returns T[]

  Remarks

  Returned as a plain array snapshot — mutating the returned array does not change the grid's expansion state. Set this property to replace the expansion set programmatically (goes through the cancellable rowExpanding event).

exportFormats

• get exportFormats(): readonly ExportFormat[]

  The export formats offered in the toolbar's export menu, in order.

  Returns readonly ExportFormat[]

  Remarks

  The community grid offers CSV only. This is the seam derived grids use to contribute more formats: @apexcharts/grid-enterprise overrides it to add 'xlsx'. The toolbar renders one menu item per entry and dispatches the chosen id to ApexGrid.exportAs.

filterExpressions

• get filterExpressions(): FilterExpression<T>[]

  Get the filter state for the grid.

  Returns FilterExpression<T>[]

• set filterExpressions(expressions: FilterExpression<T>[]): void

  Set the filter state for the grid.

  Parameters

  • expressions: FilterExpression<T>[]

  Returns void

page

• get page(): number

  The current zero-based page index.

  Returns number

pageCount

• get pageCount(): number

  The total number of pages computed from ApexGrid.totalItems and ApexGrid.pageSize.

  Returns number

pageItems

• get pageItems(): readonly T[]

  The records currently rendered into the virtualized body.

  Returns readonly T[]

  Remarks

  Equal to ApexGrid.dataView when pagination is disabled. With pagination enabled ('local' mode) this is the active page slice.

pageSize

• get pageSize(): number

  The current page size.

  Returns number

rows

• get rows(): ApexGridRow<T>[]

  Returns the collection of rendered row elements in the grid.

  Returns ApexGridRow<T>[]

  Remarks

  Since the grid has virtualization, this property returns only the currently rendered chunk of elements in the DOM.

selectedRows

• get selectedRows(): T[]

  The currently selected rows, in insertion order.

  Returns T[]

  Remarks

  Returned as a plain array snapshot — mutating the returned array does not change the grid's selection. Set this property to replace the selection programmatically (goes through the cancellable rowSelecting event).

sortExpressions

• get sortExpressions(): SortExpression<T>[]

  Get the sort state for the grid.

  Returns SortExpression<T>[]

• set sortExpressions(expressions: SortExpression<T>[]): void

  Set the sort state for the grid.

  Parameters

  • expressions: SortExpression<T>[]

  Returns void

totalItems

• get totalItems(): number

  The total number of items in the ApexGrid.dataView collection.

  Returns number

  Remarks

  This is always the post-filter, post-sort row count — pagination does not change it. Use ApexGrid.pageItems to read the rows currently rendered into the body.

announce

• announce(message: string): void

  Sets the live region's announcement text. Screen readers configured to read polite live updates will read the new value aloud.

  Parameters

  • message: string

  Returns void

  Remarks

  Use this from custom UI affordances (e.g. an "Apply filter" button) so the change is announced. Built-in operations (sort / filter / page / select / expand) call this internally already.

cancelEdit

• cancelEdit(): void

  Discards the current edit without writing back to ApexGrid.data.

  Returns void

clearFilter

• clearFilter(key?: keyof T): void

  Resets the current filter state of the control.

  Parameters

  • Optionalkey: keyof T

  Returns void

clearSelection

• clearSelection(): Promise<boolean>

  Clears the row selection.

  Returns Promise<boolean>

clearSort

• clearSort(key?: keyof T): void

  Resets the current sort state of the control.

  Parameters

  • Optionalkey: keyof T

  Returns void

collapseAllRows

• collapseAllRows(): Promise<boolean>

  Collapses every currently expanded row.

  Returns Promise<boolean>

collapseAllTreeRows

• collapseAllTreeRows(): Promise<boolean>

  Collapses every currently-expanded tree row.

  Returns Promise<boolean>

collapseRow

• collapseRow(row: T): Promise<boolean>

  Collapses row. No-op when the row is not currently expanded.

  Parameters

  • row: T

  Returns Promise<boolean>

collapseTreeRow

• collapseTreeRow(row: T): Promise<boolean>

  Collapses a tree row. No-op when the row is not currently expanded.

  Parameters

  • row: T

  Returns Promise<boolean>

commitEdit

• commitEdit(): Promise<boolean>

  Commits the current edit.

  Returns Promise<boolean>

  Remarks

  In cell mode this writes the active cell's pending value. In row mode it flushes all pending values for the active row. Emits cellValueChanging per changed cell (cancellable) and cellValueChanged after, followed by rowEditEnded in row mode.

deselectRow

• deselectRow(row: T): Promise<boolean>

  Deselects row. No-op if row is not currently selected.

  Parameters

  • row: T

  Returns Promise<boolean>

editCell

• editCell(rowIndex: number, columnKey: keyof T): Promise<boolean>

  Begins editing the cell at (rowIndex, columnKey).

  Parameters

  • rowIndex: number
  • columnKey: keyof T

  Returns Promise<boolean>

  Remarks

  rowIndex is the view-relative index (matches ApexGrid.pageItems). Returns false when the column isn't editable, the row index is out of range, or the request was rejected (for example in row mode with pending changes that couldn't be committed).

editRow

• editRow(rowIndex: number): Promise<boolean>

  Begins editing the entire row at rowIndex (row edit mode only).

  Parameters

  • rowIndex: number

  Returns Promise<boolean>

  false when editing is disabled, the grid is in cell mode, or the row index is out of range.

expandAllRows

• expandAllRows(): Promise<boolean>

  Expands every row in ApexGrid.dataView that passes the optional isExpandable predicate.

  Returns Promise<boolean>

expandAllTreeRows

• expandAllTreeRows(): Promise<boolean>

  Expands every parent row in the current tree.

  Returns Promise<boolean>

expandRow

• expandRow(row: T): Promise<boolean>

  Expands row. No-op when the row is already expanded, expansion is disabled, or the optional isExpandable predicate rejects it.

  Parameters

  • row: T

  Returns Promise<boolean>

expandTreeRow

• expandTreeRow(row: T): Promise<boolean>

  Expands a tree row. No-op when the row is already expanded, has no children, or tree mode is disabled.

  Parameters

  • row: T

  Returns Promise<boolean>

exportAs

• exportAs(formatId: string, options?: ExportOptions<T>): void

  Exports the grid in the given format (one of ApexGrid.exportFormats). Called by the toolbar's export menu. The community grid handles 'csv'; derived grids override to handle additional formats, delegating to super for the ones they don't add.

  Parameters

  • formatId: string
  • options: ExportOptions<T> = {}

  Returns void

exportToCSV

• exportToCSV(options?: CSVExportOptions<T>): string

  Exports the current grid contents as a CSV string and (in a browser context) triggers a download.

  Parameters

  • options: CSVExportOptions<T> = {}

  Returns string

  Remarks

  By default the export uses the post-filter/post-sort dataView, includes every visible column with exportable !== false, and prepends a UTF-8 BOM so Excel opens the file with the right encoding. Pass source: 'page' to export only the current page, source: 'selected' to export the current row selection, or source: 'all' to export the raw data array. The returned string is the same content written to the file — useful for tests or routing the bytes elsewhere.

  Example

  grid.exportToCSV();                                  // download data.csv
  grid.exportToCSV({ filename: 'users', source: 'selected' });
  const text = grid.exportToCSV({ filename: '' });     // string only, no download
  Copy

filter

• filter(
      config: FilterExpression<T, keyof T> | FilterExpression<T, keyof T>[],
  ): void

  Performs a filter operation in the grid based on the passed expression(s).

  Parameters

  • config: FilterExpression<T, keyof T> | FilterExpression<T, keyof T>[]

  Returns void

firstPage

• firstPage(): Promise<boolean>

  Navigates to the first page.

  Returns Promise<boolean>

getColumn

• getColumn(id: number | keyof T): ColumnConfiguration<T, keyof T> | undefined

  Returns a ColumnConfiguration for a given column.

  Parameters

  • id: number | keyof T

  Returns ColumnConfiguration<T, keyof T> | undefined

gotoPage

• gotoPage(page: number): Promise<boolean>

  Navigates the grid to the given zero-based page index.

  Parameters

  • page: number

    The target zero-based page index.

  Returns Promise<boolean>

  true if the change was applied, false if cancelled or a no-op.

  Remarks

  Emits the cancellable pageChanging event before applying the change and the pageChanged event after. Out-of-range values are clamped into [0, pageCount - 1].

  Example

  await grid.gotoPage(2);
  Copy

isRowExpanded

• isRowExpanded(row: T): boolean

  Whether row is currently expanded.

  Parameters

  • row: T

  Returns boolean

isRowSelected

• isRowSelected(row: T): boolean

  Whether row is currently selected.

  Parameters

  • row: T

  Returns boolean

isTreeRowExpanded

• isTreeRowExpanded(row: T): boolean

  Whether row is currently expanded in the tree.

  Parameters

  • row: T

  Returns boolean

lastPage

• lastPage(): Promise<boolean>

  Navigates to the last page.

  Returns Promise<boolean>

moveColumn

• moveColumn(
      fromKey: keyof T,
      toKey: keyof T,
      position?: ColumnDropPosition,
  ): Promise<boolean>

  Moves a column relative to another column.

  Parameters

  • fromKey: keyof T

    The column to move.

  • toKey: keyof T

    The reference column.

  • position: ColumnDropPosition = 'before'

    Whether to place fromKey before or after toKey. Defaults to 'before'.

  Returns Promise<boolean>

  true if the move was applied, false if cancelled or a no-op.

  Remarks

  Emits the cancellable columnMoving event first and columnMoved after. Reordering only succeeds when the source and target columns share the same pinning group (start / unpinned / end) — cross-group moves return false. Use ApexGrid.pinColumn to change a column's pinning group first.

  Example

  await grid.moveColumn('email', 'name', 'after');
  Copy

nextPage

• nextPage(): Promise<boolean>

  Navigates to the next page. No-op if already on the last page.

  Returns Promise<boolean>

pinColumn

• pinColumn(key: keyof T, position: PinPosition): Promise<boolean>

  Pins a column to one of the grid's edges, or unpins it when position is null.

  Parameters

  • key: keyof T

    The target column key.

  • position: PinPosition

    'start', 'end', or null to unpin.

  Returns Promise<boolean>

  true if the change was applied, false if cancelled or a no-op.

  Remarks

  Emits the cancellable columnPinning event first and the columnPinned event after the update is applied. The user-supplied ApexGrid.columns array is not reordered — only the visual render order changes.

  Example

  await grid.pinColumn('name', 'start');
  await grid.pinColumn('actions', 'end');
  Copy

previousPage

• previousPage(): Promise<boolean>

  Navigates to the previous page. No-op if already on the first page.

  Returns Promise<boolean>

selectAllRows

• selectAllRows(): Promise<boolean>

  Selects every row in the current view (dataView). No-op in 'single' selection mode.

  Returns Promise<boolean>

selectRow

• selectRow(row: T): Promise<boolean>

  Selects row, replacing the existing selection in 'single' mode or adding to it in 'multiple' mode.

  Parameters

  • row: T

  Returns Promise<boolean>

  true if the selection changed, false if the change was rejected by a rowSelecting listener or selection is disabled.

setPageSize

• setPageSize(size: number): Promise<boolean>

  Updates the grid's page size and returns to the first page.

  Parameters

  • size: number

    The new page size (must be a positive integer).

  Returns Promise<boolean>

  true if the change was applied, false if cancelled or a no-op.

  Remarks

  Emits the cancellable pageChanging event before applying the change and the pageChanged event after.

setQuickFilter

• setQuickFilter(value: string): Promise<boolean>

  Applies a new quick-filter (global search) value, emitting the cancellable quickFilterChanging event first and the quickFilterChanged event after the pipeline has run.

  Parameters

  • value: string

    The new quick-filter value. Pass '' to clear.

  Returns Promise<boolean>

  true if the change was applied, false if cancelled or a no-op.

  Example

  await grid.setQuickFilter('john');
  Copy

sort

• sort(
      expressions: SortExpression<T, keyof T> | SortExpression<T, keyof T>[],
  ): void

  Performs a sort operation in the grid based on the passed expression(s).

  Parameters

  • expressions: SortExpression<T, keyof T> | SortExpression<T, keyof T>[]

  Returns void

toggleRowExpansion

• toggleRowExpansion(row: T): Promise<boolean>

  Toggles expansion of row.

  Parameters

  • row: T

  Returns Promise<boolean>

toggleRowSelection

• toggleRowSelection(row: T): Promise<boolean>

  Toggles selection of row.

  Parameters

  • row: T

  Returns Promise<boolean>

toggleTreeRow

• toggleTreeRow(row: T): Promise<boolean>

  Toggles tree-expansion of row. No-op when tree mode is disabled or the row has no children.

  Parameters

  • row: T

  Returns Promise<boolean>

unpinColumn

• unpinColumn(key: keyof T): Promise<boolean>

  Unpins a column. Equivalent to ApexGrid.pinColumn(key, null).

  Parameters

  • key: keyof T

    The target column key.

  Returns Promise<boolean>

  true if the change was applied, false if the column was already unpinned or the operation was cancelled.

updateColumns

• updateColumns(
      columns:
          | ColumnConfiguration<T, keyof T>
          | ColumnConfiguration<T, keyof T>[],
  ): void

  Updates the column configuration of the grid.

  Parameters

  • columns: ColumnConfiguration<T, keyof T> | ColumnConfiguration<T, keyof T>[]

  Returns void

  Remarks

  Each updated column is replaced with a fresh object reference so that cells and headers re-render with the new template / configuration. The user-supplied columns array is also reassigned for Lit reactivity.

Staticregister

• register(): void

  Registers <apex-grid> and its internal dependencies with the custom-element registry. Idempotent — safe to call more than once.

  Returns void

  Remarks

  Registering the element is only step one of four required for a visible, styled grid. You must also configure an Ignite UI theme + CSS, give the host a bounded height, and avoid overriding display on the host. See the README "Getting Started" section for the full setup.

Staticstyles

<script>
  // Generated and unique per request:
  window.litNonce = 'a1b2c3d4';
</script>
Copy