# Theming AdapTable UI

Canonical page: https://www.adaptabletools.com/docs/handbook-theming

- AdapTable ships **`light`**, **`dark`**, and **`os`** themes — CSS variables that style Dashboard, Settings Panel, wizards, menus, and popups
- **Custom branding** overrides variables on `:root.ab--theme-light` and `:root.ab--theme-dark` in your stylesheet — start in [DevTools — Theme Builder](https://www.adaptabletools.com/docs/dev-guide-support-devtools-theme-builder/index.md), then check in exported CSS (see [Customising AdapTable Themes](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md))
- Shipped light/dark stay in sync with AG Grid theme modes; custom grid branding uses [`SystemThemeOptions.AgThemeMode`](https://www.adaptabletools.com/docs/reference/systemthemeoptions.md#agthememode) — [AG Grid Themes](https://www.adaptabletools.com/docs/handbook-theming-aggrid/index.md)

For how AdapTable UI is built — Base UI, shadcn, Tailwind (`twa:`), and accessibility — see [AdapTable UI Components](https://www.adaptabletools.com/docs/ui-components/index.md#adaptable-ui-foundation).

## Topics on this Page

| Topic                                               | Summary                            |
| --------------------------------------------------- | ---------------------------------- |
| [Designing with DevTools](#designing-with-devtools) | Theme Builder → export CSS         |
| [System themes](#system-themes)                     | `light`, `dark`, `os`, `index.css` |
| [Selecting a theme](#selecting-a-theme)             | Runtime UI and persistence         |
| [Customising](#customising-themes)                  | Handbook + variable overrides      |
| [CSS layers](#css-layers)                           | `@layer adaptable` in host apps    |
| [Co-ordinated themes](#co-ordinated-themes)         | AdapTable + AG Grid brand demo     |

## Designing with DevTools

The recommended way to explore branding is [DevTools — Theme Builder](https://www.adaptabletools.com/docs/dev-guide-support-devtools-theme-builder/index.md) on a running Grid:

- Tune **colours**, **radius**, **spacing**, and **typography** with immediate preview
- Open Settings Panel and wizards to validate tokens
- **Export CSS** and add rules to your application under `:root.ab--theme-light` / `:root.ab--theme-dark`

Install [AdapTable DevTools](https://www.adaptabletools.com/docs/dev-guide-support-devtools/index.md) from the Chrome Web Store — Theme Builder is in the **AdapTable** tab.

You only need hand-written overrides in source control after you know the values you want; the defaults are fine when they already match your app.

## System themes

AdapTable themes are named sets of [CSS variables](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties).

| Theme   | Behaviour                                                                                                                       |
| ------- | ------------------------------------------------------------------------------------------------------------------------------- |
| `light` | Default — no `CurrentTheme` required in [Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-initial-state/index.md) |
| `dark`  | Dark tokens; when selected, AdapTable applies a matching **dark** AG Grid theme mode for built-in grid themes                   |
| `os`    | Follows the operating system light/dark preference                                                                              |

Import AdapTable styles in your app:

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

### Dark theme

### Setting the dark Theme

Set `dark` as `CurrentTheme` in the `Theme` section of [Initial Adaptable State](https://www.adaptabletools.com/docs/technical-reference-initial-state/index.md)

```ts {2}
Theme: {
  CurrentTheme: "dark"
},
```

### OS theme

**Example: OS Theme**

Using OS Theme in AdapTable

- In this demo the `os` System Theme is selected by default
- AdapTable shows dark or light based on your operating system theme

- Switch the operating system theme on your computer and note how AdapTable (and AG Grid) follow.

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'OS Theme',
  initialState: {
    Dashboard: {
      ModuleButtons: ['Theme'],
      PinnedToolbars: ['Theme'],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Theme'],
        },
      ],
    },
    Theme: {
      CurrentTheme: 'os',
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'has_projects',
            'has_pages',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'week_issue_change',
          ],
          Name: 'Standard Layout',
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Selecting a theme

Users can change theme at run time (subject to [Entitlements](https://www.adaptabletools.com/docs/handbook-permissioning/index.md)) via:

- Theme [Toolbar](https://www.adaptabletools.com/docs/ui-dashboard/index.md#tabs-and-toolbars)
- Theme [Tool Panel](https://www.adaptabletools.com/docs/ui-tool-panel/index.md)
- Theme [Status Bar](https://www.adaptabletools.com/docs/ui-status-bar/index.md)
- Theme section of the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md)

The last selection is saved in user settings and restored on next load. Developers can react to changes with the [ThemeSelected event](https://www.adaptabletools.com/docs/technical-reference-theming/index.md#theme-selected-event).

## Customising themes

Override CSS variables on the shipped themes — see [Customising AdapTable Themes](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md) for key variables, component variables, palette, and demos.

Use [Referencing Theme Variables](https://www.adaptabletools.com/docs/handbook-theming-referencing/index.md) when Format Columns and other [Adaptable Styles](https://www.adaptabletools.com/docs/ui-tutorial-providing-adaptable-style/index.md) should follow the active theme via `var(--ab-color-…)`.

## CSS layers

Adaptable rules live in the [`adaptable` CSS layer](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/At-rules/@layer).

If your app uses layers, declare order so your styles can override AdapTable when needed — e.g. `@layer reset, adaptable, app, theme`. Place `adaptable` after your reset but before app utilities where appropriate.

Without layers in your app, global CSS overrides still work — layers only affect cascade among layered sheets.

Tailwind `twa:` prefix, layer ordering with Tailwind v4, and internal class policy — [Theming Technical Reference](https://www.adaptabletools.com/docs/technical-reference-theming/index.md#tailwind-integration).

## Co-ordinated themes

Custom AdapTable branding plus a custom AG Grid look uses two steps:

1. CSS variable overrides on shipped **light** / **dark** (Theme Builder or hand-written CSS)
2. Custom AG Grid theme modes with **`AgThemeMode`** on each entry in `Theme.SystemThemes`

Step-by-step for AG Grid — [AG Grid Themes](https://www.adaptabletools.com/docs/handbook-theming-aggrid/index.md#custom-ag-grid-themes). Variable reference — [Customising AdapTable Themes](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md).

**Example: Co-ordinated Themes**

Rose/red brand on AdapTable and AG Grid — switch light and dark together

- Custom CSS variables on AdapTable `light` and `dark`
- `light-red` and `dark-red` modes on `themeQuartz` in `gridOptions`
- `SystemThemes` pairs each AdapTable theme with its grid mode via `AgThemeMode`

- Use the **Theme** toolbar or status panel to switch light and dark — AdapTable and AG Grid update together
- Open **Settings Panel** to see themed panels and wizards

Demo project (Vanilla); the files without a marker are shown below:

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts        [template]
  gridOptions.ts
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts           [template]
  styles.css           [template + shown below]
index.html             [template]
package.json           [template]
tsconfig.json          [template]
```

Files marked `[template]` are the same in every demo; see the [demo template](https://www.adaptabletools.com/llms/demo-template.md#vanilla).

**`src/adaptableOptions.ts`**

```ts
import {AdaptableOptions} from '@adaptabletools/adaptable';
import {WebFramework} from './rowData';

export const adaptableOptions: AdaptableOptions<WebFramework> = {
  primaryKey: 'id',
  adaptableId: 'Co-ordinated Themes',

  initialState: {
    Theme: {
      CurrentTheme: 'light',
      SystemThemes: [
        {
          Name: 'light',
          AgThemeMode: 'light-red',
        },
        {
          Name: 'dark',
          AgThemeMode: 'dark-red',
        },
      ],
    },
    Dashboard: {
      ModuleButtons: ['Theme'],
      Tabs: [
        {
          Name: 'Default',
          Toolbars: ['Theme', 'Export', 'Layout'],
        },
      ],
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['Theme'],
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'week_issue_change',
            'open_issues_count',
            'license',
            'created_at',
            'updated_at',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

**`src/gridOptions.ts`**

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

import {rowData, WebFramework} from './rowData';
import {columnDefs} from './columnDefs';

export const gridOptions: GridOptions<WebFramework> = {
  theme: themeQuartz
    .withParams(
      {
        backgroundColor: '#FFF0F0',
        foregroundColor: '#4A1010',
        accentColor: '#C62828',
        headerBackgroundColor: '#FFCDD2',
        browserColorScheme: 'light',
      },
      'light-red'
    )
    .withParams(
      {
        backgroundColor: '#4A1010',
        foregroundColor: '#FFEBEE',
        accentColor: '#EF5350',
        headerBackgroundColor: '#6D1B1B',
        oddRowBackgroundColor: '#5C1515',
        browserColorScheme: 'dark',
      },
      'dark-red'
    ),
  defaultColDef: {
    resizable: true,
    sortable: true,
    editable: true,
    filter: true,
    floatingFilter: true,
  },
  columnDefs: columnDefs,
  rowData: rowData,
  sideBar: true,
  suppressMenuHide: true,
  columnMenu: 'new',
  cellSelection: true,
};
```

**`src/styles.css`**

```css
/*
 * Coordinated branding — rose/red palette aligned with AG Grid light-red / dark-red modes.
 * Switch themes via the Theme toolbar to see both AdapTable and the grid update together.
 */

:root.ab--theme-light {
  --ab-color-accent: #c62828;
  --ab-color-accent-foreground: #ffffff;
  --ab-color-accentlight: #ffcdd2;
  --ab-color-ring: #c62828;

  --ab-color-primary: #ffcdd2;
  --ab-color-primarylight: #fff0f0;
  --ab-color-background: #fff5f5;
  --ab-color-foreground: #4a1010;
  --ab-color-primary-foreground: #4a1010;

  --ab-color-palette-3: #ffebee;
  --ab-color-palette-4: #b71c1c;
}

:root.ab--theme-dark {
  --ab-color-accent: #ef5350;
  --ab-color-accent-foreground: #ffffff;
  --ab-color-accentlight: #6d1b1b;
  --ab-color-ring: #ef5350;

  --ab-color-primary: #6d1b1b;
  --ab-color-primarylight: #4a1010;
  --ab-color-background: #3a0e0e;
  --ab-color-foreground: #ffebeb;
  --ab-color-primary-foreground: #ffebeb;

  --ab-color-palette-3: #5c1515;
  --ab-color-palette-4: #ffcdd2;
}
```

### FAQ

**If I change the theme, will that get saved?**
Yes — the last selected theme is stored in user settings and restored on the next load.

**Which system themes ship?**
`light`, `dark`, and `os`. Branding is CSS overrides on **light** and **dark**, not separate theme files in State.

**Can grid chrome match my AdapTable brand?**
Yes — override AdapTable variables, then set matching AG Grid theme modes on `SystemThemes` with [`SystemThemeOptions.AgThemeMode`](https://www.adaptabletools.com/docs/reference/systemthemeoptions.md#agthememode) — see [Co-ordinated themes](https://www.adaptabletools.com/docs/handbook-theming/index.md#co-ordinated-themes) and [AG Grid Themes](https://www.adaptabletools.com/docs/handbook-theming-aggrid/index.md).

**What is the fastest way to design overrides?**
[DevTools — Theme Builder](https://www.adaptabletools.com/docs/dev-guide-support-devtools-theme-builder/index.md) on a live Grid, then export CSS into your app.

**Do shipped themes sync with AG Grid automatically?**
Yes for built-in AG Grid themes (`Quartz`, `Alpine`, `Balham`, `Material`). Custom grid themes need explicit `AgThemeMode` pairing.
