# AG grid

- Page: https://koobiq.io/en/components/ag-grid/overview

AG Grid is designed for working with large tables. The component supports sorting, virtual scrolling, resizing, and reordering of columns. It is based on the library [ag-grid-angular](https://www.ag-grid.com/angular-data-grid/).

[**Example: AG Grid overview** (`ag-grid-overview`)](https://koobiq.io/examples/ag-grid-overview.md)

## Table styling

To maintain a consistent table style across projects, a theme [`@koobiq/ag-grid-angular-theme`](https://github.com/koobiq/data-grid/blob/main/packages/ag-grid-angular-theme/README.md) has been created. It includes ready-to-use styles that align with the design system. The theme supports the core features of AG Grid and simplifies table appearance customization.

### Installation

Install the following packages:

```bash
npm install @koobiq/ag-grid-angular-theme@^34 ag-grid-community@^34 ag-grid-angular@^34
```

### Applying the theme

Import the theme into the main styles file `styles.scss`:

```scss
@use '@koobiq/ag-grid-angular-theme';
```

Apply the theme to `<ag-grid-angular>` in the template:

```ts
import { KbqAgGridThemeModule } from '@koobiq/ag-grid-angular-theme';
import { AgGridModule } from 'ag-grid-angular';

@Component({
    imports: [AgGridModule, KbqAgGridThemeModule],
    template: `<ag-grid-angular kbqAgGridTheme />`
})
```

The full documentation for using the theme is available [in the GitHub repository](https://github.com/koobiq/data-grid/blob/main/packages/ag-grid-angular-theme/README.md).

## Disabling cell focus styles

To disable the focus styles for table cells, add the `kbqAgGridThemeDisableCellFocusStyles` attribute to `<ag-grid-angular>`:

```html
<ag-grid-angular kbqAgGridTheme kbqAgGridThemeDisableCellFocusStyles />
```

## Row dragging

[**Example: AG Grid with row dragging** (`ag-grid-row-dragging`)](https://koobiq.io/examples/ag-grid-row-dragging.md)

## Row actions

The `kbqAgGridRowActions` directive adds an action panel that appears when hovering over a row.

[**Example: AG Grid with \`KbqAgGridRowActions\` directive** (`ag-grid-row-actions`)](https://koobiq.io/examples/ag-grid-row-actions.md)

## Row grouping

The `kbqAgGridRowGroup` directive implements client-side row grouping. Attach it to `ag-grid-angular`, supply raw data via `[kbqAgGridRowGroupRowData]` instead of `[rowData]`, and set the grouped columns via `[(kbqAgGridRowGroupCols)]`.

Collapsed/expanded group state and row selection can each be persisted independently by setting `kbqAgGridRowGroupCollapsedState` and `kbqAgGridRowGroupSelectionState` to a unique key, connecting store providers via `kbqAgGridRowGroupCollapsedStateStoreProvider` and `kbqAgGridRowGroupSelectionStateStoreProvider`.

[**Example: AG Grid with \`KbqAgGridRowGroup\` directive** (`ag-grid-row-group`)](https://koobiq.io/examples/ag-grid-row-group.md)

## Expandable rows

The `kbqAgGridRowDetail` directive expands a row to show a custom component below it. Pass the component via `kbqAgGridRowDetailComponent` and set `getRowId`. The component receives the row data and the `collapse()` method through the `KBQ_AG_GRID_ROW_DETAIL_PARAMS` token.

The behavior of expanded rows is configured with the following inputs:

| Input                            | Description                                                  |
| -------------------------------- | ------------------------------------------------------------ |
| `kbqAgGridRowDetailSingleExpand` | Keeps only one row expanded                                  |
| `kbqAgGridRowDetailFilled`       | Fills the expanded row with a background                     |
| `kbqAgGridRowDetailSticky`       | Keeps the expanded part in place during horizontal scrolling |

The directive methods are available via `#rowDetail="kbqAgGridRowDetail"`:

| Method          | Description                  |
| --------------- | ---------------------------- |
| `expand(id)`    | Expands the row              |
| `collapse(id)`  | Collapses the row            |
| `toggle(id)`    | Expands or collapses the row |
| `collapseAll()` | Collapses all rows           |

In the example, a click on a cell and Enter on a row call `toggle()`. The expanded part is not a cell, so clicking it does not collapse the row, and clicking the selection checkbox does not expand it.

The screen reader labels of the expand toggle are Russian by default. To switch the language, provide a labels provider:

```ts
providers: [kbqAgGridRowDetailLabelsProvider(KBQ_AG_GRID_ROW_DETAIL_LABELS_EN)];
```

[**Example: AG Grid with \`KbqAgGridRowDetail\` directive** (`ag-grid-row-detail`)](https://koobiq.io/examples/ag-grid-row-detail.md)

## Actions panel for selected rows

The [Actions panel](https://koobiq.io/en/components/actions-panel.md) component allows you to perform bulk actions on rows selected in the table. To prevent the panel from overlapping the last rows of the table, a `padding-bottom` is added to `.ag-body-viewport` when it opens.

[**Example: Ag-grid and actions-panel example** (`ag-grid-and-actions-panel`)](https://koobiq.io/examples/ag-grid-and-actions-panel.md)

## Content panel for the selected row

The [Content panel](https://koobiq.io/en/components/content-panel.md) component shows a quick preview of the row selected in the table, shifting the table instead of covering it.

[**Example: Ag-grid and content-panel example** (`ag-grid-and-content-panel`)](https://koobiq.io/examples/ag-grid-and-content-panel.md)

## Long lists in cells

A long list can fit into a single line of a cell: [Overflow items](https://koobiq.io/en/components/overflow-items.md) hides what does not fit the width and recalculates that whenever the column is resized. The hidden items can be expanded in the cell itself or shown as a full list in a [Popover](https://koobiq.io/en/components/popover.md). To let the row height follow the content, enable `autoHeight` for the column.

[**Example: AG Grid with overflow items** (`ag-grid-long-cell-content`)](https://koobiq.io/examples/ag-grid-long-cell-content.md)

## Copying selected rows

The `kbqAgGridCopyByCtrlC` directive allows you to copy selected rows to the clipboard using the `Ctrl+C` keyboard shortcut.

[**Example: AG Grid with \`KbqAgGridCopyByCtrlC\` directive** (`ag-grid-copy-selected`)](https://koobiq.io/examples/ag-grid-copy-selected.md)

## Export

The grid's own API can be used to export the currently displayed data (respecting active filters, sorting, and formatters). `api.exportDataAsCsv()` downloads a CSV file with no additional dependencies. Other formats can be built on top of the grid's cell values using third-party libraries — for example, XLSX via [`write-excel-file`](https://www.npmjs.com/package/write-excel-file), and PDF via [`jspdf`](https://www.npmjs.com/package/jspdf) with [`jspdf-autotable`](https://www.npmjs.com/package/jspdf-autotable).

[**Example: AG Grid with CSV, XLSX and PDF export** (`ag-grid-export`)](https://koobiq.io/examples/ag-grid-export.md)

## Status bar

The `kbqAgGridStatusBar` directive adds a customizable panel below the table.

[**Example: AG Grid with \`KbqAgGridStatusBar\` directive** (`ag-grid-status-bar`)](https://koobiq.io/examples/ag-grid-status-bar.md)

## State persistence

Directives save and restore grid state across page reloads.

`LocalStorageStore` is used by default. Switch to `QueryParamsStore` if needed.

### Columns

The `kbqAgGridColumnState` directive saves sort order, column order, visibility, and width. Add it with a unique key and connect the store provider via `kbqAgGridColumnStateStoreProvider`.

[**Example: AG Grid with \`KbqAgGridColumnState\` directive** (`ag-grid-column-state`)](https://koobiq.io/examples/ag-grid-column-state.md)

### Filters

The `kbqAgGridFilterState` directive saves column filter models. Add it with a unique key and connect the store provider via `kbqAgGridFilterStateStoreProvider`.

[**Example: AG Grid with \`KbqAgGridFilterState\` directive** (`ag-grid-filter-state`)](https://koobiq.io/examples/ag-grid-filter-state.md)

### Quick filter

The `kbqAgGridQuickFilterState` directive saves the quick filter value. Add it with a unique key, connect the store provider via `kbqAgGridQuickFilterStateStoreProvider`, and bind the input value via `[(kbqAgGridQuickFilterStateValue)]`.

[**Example: AG Grid with \`KbqAgGridQuickFilterState\` directive** (`ag-grid-quick-filter-state`)](https://koobiq.io/examples/ag-grid-quick-filter-state.md)

### External filter

The `kbqAgGridExternalFilterState` directive saves the external filter value. Add it with a unique key, connect the store provider via `kbqAgGridExternalFilterStateStoreProvider`, bind the value via `[(kbqAgGridExternalFilterStateValue)]`, and pass the row check function via `kbqAgGridExternalFilterStatePass`.

[**Example: AG Grid with \`KbqAgGridExternalFilterState\` directive** (`ag-grid-external-filter-state`)](https://koobiq.io/examples/ag-grid-external-filter-state.md)

### Rows

The `kbqAgGridRowSelectionState` directive saves row selection. Add it with a unique key, connect the store provider via `kbqAgGridRowSelectionStateStoreProvider`, and set `getRowId`.

[**Example: AG Grid with \`KbqAgGridRowSelectionState\` directive** (`ag-grid-row-selection-state`)](https://koobiq.io/examples/ag-grid-row-selection-state.md)

### Focus

The `kbqAgGridRowFocusState` directive saves the focused cell. Add it with a unique key, connect the store provider via `kbqAgGridRowFocusStateStoreProvider`, and set `getRowId`.

[**Example: AG Grid with \`KbqAgGridRowFocusState\` directive** (`ag-grid-row-focus-state`)](https://koobiq.io/examples/ag-grid-row-focus-state.md)

## Table settings menu

The `kbqAgGridSettingsMenu` directive adds a table settings button in the top-right corner of the grid. By default, the menu contains two items:

| Item                                 | Description                                                        |
| ------------------------------------ | ------------------------------------------------------------------ |
| `kbqAgGridSettingsMenuColumnsItem()` | Showing, hiding, reordering and pinning columns, searching by name |
| `kbqAgGridSettingsMenuSortItem()`    | Sorting by several columns                                         |

The reset button restores the columns and the sorting to their initial state.

Constraints are configured via `ColDef`:

- `lockVisible: true` prevents hiding a column. The last visible column can never be hidden regardless.
- `lockPinned: true` prevents pinning and unpinning a column.

Russian labels are used by default. To switch the language, provide the labels providers:

```ts
providers: [
    kbqAgGridSettingsMenuLabelsProvider(KBQ_AG_GRID_SETTINGS_MENU_LABELS_EN),
    kbqAgGridColumnMenuLabelsProvider(KBQ_AG_GRID_COLUMN_MENU_LABELS_EN)
];
```

[**Example: AG Grid with \`KbqAgGridSettingsMenu\` directive** (`ag-grid-settings-menu`)](https://koobiq.io/examples/ag-grid-settings-menu.md)

## Loading overlay

The `kbqAgGridLoadingOverlay` directive controls the grid loading state: when the value is `true`, a skeleton overlay is shown on top of the rows.

The skeleton placeholder takes the place of the grid before loading. Regardless of the contents of the future grid, the placeholder consists of a header, 3 columns and 3 rows. The number of columns and rows can be adjusted via `kbqAgGridLoadingOverlayConfigProvider`. The first column has a fixed size, the rest stretch equally. The placeholder bars in the cells imitate the real content and have different widths.

After the grid is initialized, the data starts loading. For consistency, the placeholder of three rows stays during loading, but now it reflects the real set of columns and their widths, and the selection column. The placeholder bars in the cells still have different widths to imitate the real content.

[**Example: AG Grid with loading overlay** (`ag-grid-loading-overlay`)](https://koobiq.io/examples/ag-grid-loading-overlay.md)

## Skeleton cell renderer

`KbqAgGridSkeletonCellRenderer` shows a skeleton in cells of rows the infinite row model (`rowModelType="infinite"`) has not loaded yet. The selection column has its own skeleton: while there is no data, the checkbox is unavailable.

[**Example: AG Grid with skeleton cell renderer** (`ag-grid-skeleton-cell-renderer`)](https://koobiq.io/examples/ag-grid-skeleton-cell-renderer.md)

## Load error

On the initial load, the grid immediately requests the first and the second portions of data, and while scrolling it stays one step ahead of the user.

If a portion fails to load, the `kbqAgGridLoadError` directive shows an error message with a retry link on the last row:

- the message scrolls vertically together with the rows;
- during horizontal scrolling, the message stays in the visible area of the grid;
- the message takes up the whole visible area of the grid, even with pinned columns;
- if row dividers appear or the row height changes, the message adapts to the overall styling.

To see these cases in the example, switch the options under the grid.

[**Example: AG Grid with a load error row** (`ag-grid-load-error`)](https://koobiq.io/examples/ag-grid-load-error.md)

If the grid has no skeletons, a text loading indicator can be shown while data is loading. It spans the whole row width, so the selection column does not shift its label.

[**Example: AG Grid with a text loading indicator** (`ag-grid-load-text`)](https://koobiq.io/examples/ag-grid-load-text.md)

## Row selection with infinite scrolling

With infinite scrolling, data is loaded in blocks, so it is not possible to select all rows using a regular list — most of them are not yet loaded. The `kbqAgGridInfiniteSelection` directive inverts the selection: instead of a list of selected rows, it stores an "all selected" flag and a list of exceptions.

This state mirrors the condition "all except the specified IDs", so it can be passed to the server without loading all rows.

The directive requires two parameters:

- `kbqAgGridInfiniteSelectionDatasource` accepts a data source. When all rows are selected, newly loaded blocks are automatically added to the selection.
- `getRowId` returns a stable unique row identifier.

[**Example: AG Grid with infinite selection** (`ag-grid-infinite-selection`)](https://koobiq.io/examples/ag-grid-infinite-selection.md)

## Custom keyboard shortcuts

You can add custom keyboard shortcuts by adding the appropriate directives to your `<ag-grid-angular>` component.

| Key           | Action                 | Directive                         |
| ------------- | ---------------------- | --------------------------------- |
| Tab           | Move to next row       | `kbqAgGridToNextRowByTab`         |
| Shift + ↓↑    | Select multiple rows   | `kbqAgGridSelectRowsByShiftArrow` |
| Ctrl + click  | Select a row           | `kbqAgGridSelectRowsByCtrlClick`  |
| Ctrl + C      | Copy selected rows     | `kbqAgGridCopyByCtrlC`            |
| Shift + click | Select a range of rows | `kbqAgGridSelectRowsByShiftClick` |
| Ctrl + A      | Select all rows        | `kbqAgGridInfiniteSelection`      |

More information about keyboard shortcuts can be found in the [ag-grid-angular documentation](https://www.ag-grid.com/angular-data-grid/keyboard-navigation/).

## Recommendations

- Use the [Table](https://koobiq.io/en/components/table.md) component for simple tables with a small amount of data that do not require resizing or reordering of columns.
- If the list contains only one column, use [List](https://koobiq.io/en/components/list.md) or [Tree](https://koobiq.io/en/components/tree.md).
