# Integrating AdapTable React

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

- To use AdapTable React, you need to import `{ Adaptable }` from `@adaptabletools/adaptable-react-aggrid` 
- You also need to provide 3 components: `Adaptable.Provider`, `Adaptable.UI` & `Adaptable.AgGridReact`
- 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="react" />

## 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 React project with rows fetched from https://api.example.com/trades
</AiSkill>

## Manual integration

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

### React Components

There are 3 key React 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 Components including the [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md)                                  |
| **`Adaptable.AgGridReact`** | thin AdapTable wrapper around the AG Grid React component                                                                             |

### Defining the 3 React Components

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).

Pass the array to `<Adaptable.Provider />` in Step 7.

```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,
};
```

- 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` and the types you need from `@adaptabletools/adaptable-react-aggrid`.

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

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

```ts
import '@adaptabletools/adaptable-react-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 5

```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 3 **mandatory props**:

- `gridOptions` — GridOptions object created in Step 2
- `modules` — AG Grid Modules array created in Step 1
- `adaptableOptions` — Adaptable Options created in Step 6

Inside the Provider, render:

- `<Adaptable.UI />` for AdapTable's UI and [Dashboard](https://www.adaptabletools.com/docs/ui-dashboard/index.md)
- `<Adaptable.AgGridReact />` — **not** `<AgGridReact />` directly

```tsx
<Adaptable.Provider
  gridOptions={gridOptions}
  modules={agGridModules}
  adaptableOptions={adaptableOptions}>
  <Adaptable.UI style={{flex: 'none'}} />
  <div style={{flex: 1}}>
    <Adaptable.AgGridReact />
  </div>
</Adaptable.Provider>
```

- `Adaptable.AgGridReact` should **not** receive a `gridOptions` or `modules` prop; pass those to `Adaptable.Provider`

Add `onAdaptableReady` on `Adaptable.Provider`.

This Event is fired when AdapTable is initialised, and should be used to perform any setup related actions required.

The [`AdaptableReadyInfo`](https://www.adaptabletools.com/docs/reference/adaptablereadyinfo.md) object provided by the Event contains two key 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

```tsx
<Adaptable.Provider
  gridOptions={gridOptions}
  modules={agGridModules}
  adaptableOptions={adaptableOptions}
  onAdaptableReady={({adaptableApi, agGridApi}: AdaptableReadyInfo) => {
    adaptableApi.quickSearchApi.runQuickSearch('toy');
    agGridApi.autoSizeAllColumns();
  }}>
  <Adaptable.UI style={{flex: 'none'}} />
  <div style={{flex: 1}}>
    <Adaptable.AgGridReact />
  </div>
</Adaptable.Provider>
```

### Minimum Working Example

```tsx
import {useRef} from 'react';
import {
  LicenseManager,
  themeQuartz,
  type GridOptions,
  type Module,
} from 'ag-grid-enterprise';
import {AllEnterpriseModule} from 'ag-grid-enterprise';
import {AgChartsEnterpriseModule} from 'ag-charts-enterprise';
import {
  Adaptable,
  type AdaptableApi,
  type AdaptableOptions,
  type AdaptableReadyInfo,
  type InitialState,
} from '@adaptabletools/adaptable-react-aggrid';
import '@adaptabletools/adaptable-react-aggrid/index.css';

LicenseManager.setLicenseKey('<AG_GRID_LICENSE_KEY_HERE>');

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

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,
};

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

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

export const AdaptableGrid = () => {
  const adaptableApiRef = useRef<AdaptableApi | null>(null);

  const onAdaptableReady = ({adaptableApi, agGridApi}: AdaptableReadyInfo) => {
    adaptableApiRef.current = adaptableApi;
    adaptableApi.quickSearchApi.runQuickSearch('toy');
    agGridApi.autoSizeAllColumns();
  };

  return (
    <Adaptable.Provider
      gridOptions={gridOptions}
      modules={agGridModules}
      adaptableOptions={adaptableOptions}
      onAdaptableReady={onAdaptableReady}>
      <Adaptable.UI style={{flex: 'none'}} />
      <div style={{flex: 1}}>
        <Adaptable.AgGridReact />
      </div>
    </Adaptable.Provider>
  );
};
```

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)
- [AdapTable React Hooks](https://www.adaptabletools.com/docs/react-adaptable-hooks/index.md)

### FAQ

**Why do I have a 'multiple versions of React' message?**
AdapTable uses React internally and has a minimum required version.
If you are using other imports / libraries which require a lower version of React than this, then you will get this message, as `npm` will install a separate version of React for AdapTable (this happens if you have `node_modules/@adaptabletools/adaptable/node_modules/react` present).
You can also figure out why React is installed by running the `npm ls react` command.

**Should I use your Redux store or my own?**
Use your own. Although the general advice is one store per application, the best practice when you are using an external component (like AdapTable) is to have separate stores.
You can subscribe to AdapTable's store, but in practice we strongly recommend using the [Adaptable State Changed Event](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-events/index.md) instead — it gives you the same information in a more structured and safe way.

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).
