# Integrating AdapTable Angular

Canonical page: https://www.adaptabletools.com/docs/angular-integration

- AdapTable Angular requires 3 Angular Components: `adaptable-provider`, `adaptable-ui` & `ag-grid-angular`
- You can either leverage the [adaptable-setup](https://www.adaptabletools.com/docs/getting-started-ai-skills-setup/index.md) AI Agent Skill or integrate manually

## Integration Options

<IntegrationRoutes framework="angular" />

## Agent Integration

Simply leverage the [adaptable-setup](https://www.adaptabletools.com/docs/getting-started-ai-skills-setup/index.md) AI skill, providing all relevant information:

<AiSkill skill="adaptable-setup" embedded>
add AdapTable to this AG Grid app
<br />
set up AdapTable in a new Angular project with rows fetched from https://api.example.com/trades
</AiSkill>

## Manual integration

The sections below walk through the Angular components and a minimum working example.

### Defining Key Components

There are 3 key Angular components that need to be provided:

| Component                  | Purpose                                                                                                                               |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| **`<adaptable-provider>`** | manages [Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state/index.md) and orchestrates the AdapTable and AG Grid components |
| **`<adaptable-ui>`**       | renders AdapTable's UI including the [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md)                                             |
| **`<ag-grid-angular>`**    | standard AG Grid Angular component with the `*adaptable` structural directive applied                                                 |

### Minimum Working Example

This uses a standalone Angular component (the default for Angular 20).

```ts
import {Component} from '@angular/core';
import {AgGridAngular} from 'ag-grid-angular';
import {
  LicenseManager,
  themeQuartz,
  type GridOptions,
  type Module,
} from 'ag-grid-enterprise';
import {AllEnterpriseModule} from 'ag-grid-enterprise';
import {AgChartsEnterpriseModule} from 'ag-charts-enterprise';
import {
  AdaptableProvider,
  AdaptableUI,
  AdaptableAgGridDirective,
  type AdaptableApi,
  type AdaptableOptions,
  type AdaptableReadyInfo,
  type InitialState,
} from '@adaptabletools/adaptable-angular-aggrid';
import '@adaptabletools/adaptable-angular-aggrid/index.css';

LicenseManager.setLicenseKey('<AG_GRID_LICENSE_KEY_HERE>');

@Component({
  selector: 'app-root',
  imports: [
    AdaptableProvider,
    AdaptableUI,
    AdaptableAgGridDirective,
    AgGridAngular,
  ],
  template: `
    <adaptable-provider
      [adaptableOptions]="adaptableOptions"
      [gridOptions]="gridOptions"
      [modules]="agGridModules"
      (adaptableReady)="adaptableReady($event)">
      <adaptable-ui style="flex: none"></adaptable-ui>
      <ag-grid-angular
        *adaptable="let adaptable"
        [gridOptions]="adaptable.gridOptions"
        [modules]="adaptable.modules"
        style="flex: 1">
      </ag-grid-angular>
    </adaptable-provider>
  `,
})
export class AppComponent {
  agGridModules: Module[] = [
    AllEnterpriseModule.with(AgChartsEnterpriseModule),
  ];

  gridOptions: GridOptions = {
    theme: themeQuartz,
    columnDefs: [
      {headerName: 'Id', field: 'id', cellDataType: 'number'},
      {headerName: 'Make', field: 'make', filter: true, cellDataType: 'text'},
      {
        headerName: 'Model',
        field: 'model',
        editable: true,
        cellDataType: 'text',
      },
      {headerName: 'Price', field: 'price', cellDataType: 'number'},
    ],
    rowData: [
      {id: 1, make: 'Toyota', model: 'Yaris', price: 40000},
      {id: 2, make: 'Toyota', model: 'Corolla', price: 28000},
      {id: 3, make: 'Ford', model: 'Mondeo', price: 32000},
    ],
    cellSelection: true,
    sideBar: true,
  };

  initialState: InitialState = {
    Dashboard: {
      PinnedToolbars: ['Layout', 'Export'],
    },
    Layout: {
      CurrentLayout: 'Cars',
      Layouts: [
        {
          Name: 'Cars',
          TableColumns: ['id', 'make', 'model', 'price'],
        },
      ],
    },
  };

  adaptableOptions: AdaptableOptions = {
    licenseKey: '<ADAPTABLE_LICENSE_KEY_HERE>',
    primaryKey: 'id',
    userName: 'Demo User',
    adaptableId: 'Basic Setup',
    initialState: this.initialState,
  };

  adaptableApi?: AdaptableApi;

  adaptableReady = ({adaptableApi, agGridApi}: AdaptableReadyInfo) => {
    this.adaptableApi = adaptableApi;
    adaptableApi.quickSearchApi.runQuickSearch('toy');
    agGridApi.autoSizeAllColumns();
  };
}
```

### Defining the 3 Angular Components

In a standalone component, import:

- `AdaptableProvider`, `AdaptableUI` and `AdaptableAgGridDirective` from `@adaptabletools/adaptable-angular-aggrid`
- `AgGridAngular` from `ag-grid-angular`

```ts
import {Component} from '@angular/core';
import {AgGridAngular} from 'ag-grid-angular';
import {
  AdaptableProvider,
  AdaptableUI,
  AdaptableAgGridDirective,
} from '@adaptabletools/adaptable-angular-aggrid';

@Component({
  selector: 'app-root',
  imports: [
    AdaptableProvider,
    AdaptableUI,
    AdaptableAgGridDirective,
    AgGridAngular,
  ],
  template: `<!-- see Step 8 -->`,
})
export class AppComponent {}
```

If you still use `NgModule`, import `AdaptableAngularAgGridModule` and `AgGridModule` instead of listing the standalone components in `imports`.

Import the [AG Grid Enterprise Modules](https://www.adaptabletools.com/docs/getting-started-aggrid-modules/index.md).

The support templates use the Enterprise bundle together with AG Charts. That covers AG Grid Charts and [AdapTable Sparkline Columns](https://www.adaptabletools.com/docs/handbook-styled-column-sparkline/index.md).

```ts
import {AllEnterpriseModule, type Module} from 'ag-grid-enterprise';
import {AgChartsEnterpriseModule} from 'ag-charts-enterprise';

export const agGridModules: Module[] = [
  AllEnterpriseModule.with(AgChartsEnterpriseModule),
];
```

- To register only the modules your feature set needs, see [AG Grid Modules](https://www.adaptabletools.com/docs/getting-started-aggrid-modules/index.md)
- In AG Grid 36 the Client-Side Row Model is part of the grid core, so `ClientSideRowModelModule` is not required

Define and populate a standard AG Grid [GridOptions](https://www.ag-grid.com/javascript-data-grid/grid-interface/#grid-options) object.

Provide all required AG Grid related information including:

- AG Grid theme (`themeQuartz` in this example)
- column schema (including the correct [cell data types](https://www.adaptabletools.com/docs/dev-guide-aggrid-cell-data-types/index.md))
- initial data (if not lazy loading)
- AG Grid events
- additional, required properties

```ts
import {themeQuartz, type GridOptions} from 'ag-grid-enterprise';

const gridOptions: GridOptions = {
  theme: themeQuartz,
  columnDefs: [
    {headerName: 'Id', field: 'id', cellDataType: 'number'},
    {headerName: 'Make', field: 'make', filter: true, cellDataType: 'text'},
    {headerName: 'Model', field: 'model', editable: true, cellDataType: 'text'},
    {headerName: 'Price', field: 'price', cellDataType: 'number'},
  ],
  rowData: [
    {id: 1, make: 'Toyota', model: 'Yaris', price: 40000},
    {id: 2, make: 'Toyota', model: 'Corolla', price: 28000},
    {id: 3, make: 'Ford', model: 'Mondeo', price: 32000},
  ],
  cellSelection: true,
  sideBar: true,
};
```

- **All GridOptions properties** should be included in the `gridOptions` Input (not as direct Inputs on the `<ag-grid-angular>` component)
- This approach ensures a consistent and streamlined interface for grid configuration in all scenarios (lazy loading, server-side data, etc.)

- The [rowData](https://www.ag-grid.com/angular-data-grid/grid-options/#reference-clientRowModel-rowData) prop is the **only exception** and has flexibility to be passed as a separate input to the `<ag-grid-angular>` component
- However, this is not mandatory, and it can also be included within the `gridOptions` Input, with the other props

- Always set the appropriate `cellDataType` property in ColumnDefs for every Column, to enable [AdapTable to use the correct Filters and related properties](https://www.adaptabletools.com/docs/dev-guide-aggrid-cell-data-types/index.md)
- Many ColDef properties are **ignored** by AdapTable and replaced by [Layout](https://www.adaptabletools.com/docs/handbook-layouts/index.md) props - see full details in [Guide to Layouts and ColDefs](https://www.adaptabletools.com/docs/dev-guide-columns-configuring-coldefs/index.md)

- AG Grid Enterprise also requires its own license key
- Set it with `LicenseManager.setLicenseKey` from `ag-grid-enterprise` (the support template shows this)

Import AdapTable Types from `@adaptabletools/adaptable-angular-aggrid` (e.g. `AdaptableApi`, `AdaptableOptions`, `InitialState`)

```ts
import {
  type AdaptableApi,
  type AdaptableOptions,
  type AdaptableReadyInfo,
  type InitialState,
} from '@adaptabletools/adaptable-angular-aggrid';
```

`index.css` contains core styles (and supports both `light` and `dark` themes)

```ts
import '@adaptabletools/adaptable-angular-aggrid/index.css';
```

- AdapTable's styles use the `adaptable` CSS layer - so you can access that to control specificity
- If your app is using Tailwind, we recommend using this CSS layer order: `@layer theme, base, components, adaptable, utilities`
- See [AdapTable Theming Guide](https://www.adaptabletools.com/docs/handbook-theming/index.md) for full details on choosing and extending AdapTable Themes

Add the [Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md) that is required to ship AdapTable with the objects you require for initial use.

This will later get merged into [Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state/index.md), together with any changes made by the run-time user.

It **must** include a `Layouts` section, containing at least one [Layout](https://www.adaptabletools.com/docs/handbook-layouts/index.md) (unless using [Default Layouts](https://www.adaptabletools.com/docs/handbook-layouts-default/index.md)).

In this example we:

- Pin the `Layout` and `Export` Toolbars on the [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md)
- Create a [Layout](https://www.adaptabletools.com/docs/handbook-layouts/index.md) "Cars" whose ColumnIds match the ColDef `field` values

```ts
const initialState: InitialState = {
  Dashboard: {
    PinnedToolbars: ['Layout', 'Export'],
  },
  Layout: {
    CurrentLayout: 'Cars',
    Layouts: [
      {
        Name: 'Cars',
        TableColumns: ['id', 'make', 'model', 'price'],
      },
    ],
  },
};
```

[Adaptable Options](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md) defines exactly how AdapTable should work.

Every instance needs:

- a [Primary Key](https://www.adaptabletools.com/docs/getting-started-primary-key/index.md) — a unique column
- an [Adaptable Id](https://www.adaptabletools.com/docs/getting-started-adaptable-id/index.md) which uniquely identifies the Grid
- the [License Key](https://www.adaptabletools.com/docs/getting-started-license-key/index.md) provided when you purchase AdapTable
- a [User Name](https://www.adaptabletools.com/docs/getting-started-user-name/index.md) to identify the current user
- the `initialState` created in Step 6

```ts
const adaptableOptions: AdaptableOptions = {
  licenseKey: '<ADAPTABLE_LICENSE_KEY_HERE>',
  primaryKey: 'id',
  userName: 'Demo User',
  adaptableId: 'Basic Setup',
  initialState,
};
```

Adaptable Options supports [TypeScript Generics](https://www.adaptabletools.com/docs/technical-reference-adaptable-options/index.md#typescript-generics) which ensures a better developer experience by providing the row data type

If the `licenseKey` property is not present, AdapTable will display a watermark and run with reduced functionality

Often added next: [Entitlements](https://www.adaptabletools.com/docs/handbook-permissioning/index.md), [Plugins](https://www.adaptabletools.com/docs/technical-reference-plugins/index.md), and [remote State persistence](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-persistence/index.md#remote-storage)

Render `<adaptable-provider>` with these **mandatory** inputs:

- `adaptableOptions` — the object created in Step 7
- `gridOptions` — GridOptions object created in Step 3
- `modules` — Modules array created in Step 2

Inside the provider, render `<adaptable-ui>` and `<ag-grid-angular>` with AdapTable's `*adaptable` structural directive.

`<ag-grid-angular>` must take `gridOptions` and `modules` from the AdapTable context — not from the parent component.

```html
<adaptable-provider
  [adaptableOptions]="adaptableOptions"
  [gridOptions]="gridOptions"
  [modules]="agGridModules"
  (adaptableReady)="adaptableReady($event)">
  <adaptable-ui style="flex: none"></adaptable-ui>
  <ag-grid-angular
    *adaptable="let adaptable"
    [gridOptions]="adaptable.gridOptions"
    [modules]="adaptable.modules"
    style="flex: 1">
  </ag-grid-angular>
</adaptable-provider>
```

- The `<ag-grid-angular>` component should get its `gridOptions` and `modules` Inputs from the Adaptable context
- They should **not** be given directly from the parent component

- Always use a single `gridOptions` Input for **all** grid related props, not as direct Inputs on the `<ag-grid-angular>` component
- This ensures a consistent and streamlined grid configuration in all scenarios (lazy loading, server-side data, etc.)

The [Adaptable Ready Event](https://www.adaptabletools.com/docs/getting-started-adaptable-ready/index.md) is fired when AdapTable is initialised, and should be used to perform any setup related actions required.

Bind `(adaptableReady)` on `<adaptable-provider>` and handle it on the component class.

The [`AdaptableReadyInfo`](https://www.adaptabletools.com/docs/reference/adaptablereadyinfo.md) object provided by the Event contains 2 important objects:

- `adaptableApi` which gives access to the [Adaptable API](https://www.adaptabletools.com/docs/technical-reference-adaptable-api/index.md)
- `agGridApi` which gives access to AG Grid's Api

```ts
adaptableReady = ({adaptableApi, agGridApi}: AdaptableReadyInfo) => {
  this.adaptableApi = adaptableApi;
  adaptableApi.quickSearchApi.runQuickSearch('toy');
  agGridApi.autoSizeAllColumns();
};
```

- AG Grid's `gridReady` event should **not** be used - because it will fire **before** AdapTable has initialised
- Instead, you should always use AdapTable's `adaptableReady` event

See the [Integration](https://www.adaptabletools.com/docs/getting-started-integration/index.md) section in Getting Started for related articles on:
- [Choosing a Primary Key](https://www.adaptabletools.com/docs/getting-started-primary-key/index.md)
- [Setting the Adaptable Id](https://www.adaptabletools.com/docs/getting-started-adaptable-id/index.md)
- [Providing a User Name](https://www.adaptabletools.com/docs/getting-started-user-name/index.md)
- [Creating Adaptable Context](https://www.adaptabletools.com/docs/dev-guide-tutorial-providing-adaptable-context/index.md)
- [Configuring the Adaptable State Key](https://www.adaptabletools.com/docs/getting-started-adaptable-state-key/index.md)
- [Providing Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md)
- [Managing Remote State Persistence](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-persistence/index.md#remote-storage)
- [Supplying the AdapTable License Key](https://www.adaptabletools.com/docs/getting-started-license-key/index.md)
- [Layouts vs ColDefs](https://www.adaptabletools.com/docs/dev-guide-columns-configuring-coldefs/index.md)
- [Setting Cell Data Types](https://www.adaptabletools.com/docs/dev-guide-aggrid-cell-data-types/index.md)
- [Listening to Adaptable Ready Event](https://www.adaptabletools.com/docs/getting-started-adaptable-ready/index.md)
- [Testing AdapTable](https://www.adaptabletools.com/docs/getting-started-testing/index.md)
- [Selecting or Creating an AdapTable Theme](https://www.adaptabletools.com/docs/handbook-theming/index.md)

### FAQ

**I get an error message: Uncaught TypeError: Cannot read properties of undefined (reading 'api')**
Make sure that you are passing in all GridOptions properties directly on the GridOptions object itself, and not as direct Inputs on the `<ag-grid-angular>` component

Common first-run questions (modules, cell data types, browsers, watermarks) are on the [Getting Started FAQ](https://www.adaptabletools.com/docs/getting-started-faq/index.md).
