# Adaptable Style Object

Canonical page: https://www.adaptabletools.com/docs/ui-tutorial-providing-adaptable-style

- The Adaptable Style object is the common UI interface for all [Adaptable Object](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md#adaptable-objects) 
- It can comprise either a group of style-related properties or a CSS Classname to be used
- Run-time users set colours via the [Colour Picker](https://www.adaptabletools.com/docs/ui-tutorial-custom-colour-palette/index.md) in wizards

## Topics on this Page

| Topic                                                  | Summary                        |
| ------------------------------------------------------ | ------------------------------ |
| [Where styles apply](#using-adaptable-style)           | Modules using `AdaptableStyle` |
| [Wizard UI](#using-adaptable-style)                    | Colour picker in wizards       |
| [Properties & ClassName](#configuring-adaptable-style) | Fields and CSS class option    |
| [FAQ](#faq)                                            | Transparency and rgba          |

[UI Guides](https://www.adaptabletools.com/docs/ui-tutorial-overview/index.md).

There are several places in AdapTable where a custom style can be provided, including:

- [Column Formatting](https://www.adaptabletools.com/docs/handbook-column-formatting/index.md) — base styling on a column, optionally rule-driven
- [Quick Search](https://www.adaptabletools.com/docs/handbook-quick-search/index.md) — highlighting matched cells
- [Flashing Cells](https://www.adaptabletools.com/docs/handbook-flashing-cell/index.md) — the up / down flash colours
- [Alerts](https://www.adaptabletools.com/docs/handbook-alerting/index.md) — the alert-row highlight style
- [Styled Columns](https://www.adaptabletools.com/docs/handbook-styled-column-overview/index.md) — every styled column type accepts at least one slice of the same object (e.g. [Badge](https://www.adaptabletools.com/docs/handbook-styled-column-badge/index.md), [Gradient](https://www.adaptabletools.com/docs/handbook-styled-column-gradient/index.md), [Rating](https://www.adaptabletools.com/docs/handbook-styled-column-rating/index.md), [Sparkline](https://www.adaptabletools.com/docs/handbook-styled-column-sparkline/index.md), etc.)

- All of these styles are defined using the same [`AdaptableStyle`](https://www.adaptabletools.com/docs/reference/adaptablestyle.md) object
- Styled Columns typically use only one of its two reusable halves (`CellFontStyle` for text, `CellBoxStyle` for chrome)

## Using Adaptable Style

The Adaptable UI makes it easy for run-time users to set an Adaptable Style when creating an object.

### Setting an Adaptable Style in a Settings Panel Wizard

These are the steps involved:

There are 3 Colour properties that can be provided to colour different parts of the Cell:

- Back Colour
- Fore (i.e. font) Colour
- Border Colour

The wizard opens the AdapTable [Colour Picker](https://www.adaptabletools.com/docs/ui-tutorial-custom-colour-palette/index.md) (Custom and Palette tabs).

For each Colour property, an `Opacity` can also be set allowing for transparency to be added.

- AdapTable provides a default set of colours to display in the Colour Picker
- However these can be customised by developers via theme CSS variables (see [Providing a Custom Colour Palette](https://www.adaptabletools.com/docs/ui-tutorial-custom-colour-palette/index.md))

Provide a numeric Radius for the border of the Cell

There are 2 Font Style Properties that can be selected:

- Bold
- Italic

There are 3 Text Decoration properties that can be selected:

- Underline
- Strikethrough
- Overline

- Only one of these can be selected — they are mutually exclusive
- The wizard label "Strikethrough" maps to the API value `TextDecoration: 'LineThrough'` (the underlying CSS keyword), so when setting it through [Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md) use `'LineThrough'`, not `'Strikethrough'`

There are 6 properties available for Font Size:

- Default (i.e. what is already provided through CSS will be used)
- XSmall
- Small
- Medium
- Large
- XLarge

Choose how Cells will align in the formatted Cells. Options are:

- left
- centre
- right

Un-pressing all three buttons clears any explicit override and lets the column / grid default win. When set through the API this corresponds to `Alignment: 'Default'` (which AdapTable treats the same as omitting the property).

If any [Css ClassNames](#css-class-option) have been provided in [User Interface Options](https://www.adaptabletools.com/docs/technical-reference-ui/index.md) a dropdown will be displayed allowing this to be used instead of creating a Style.

## Configuring Adaptable Style

The [`AdaptableStyle`](https://www.adaptabletools.com/docs/reference/adaptablestyle.md) extends 2 objects - [`CellFontStyle`](https://www.adaptabletools.com/docs/reference/cellfontstyle.md) and [`CellBoxStyle`](https://www.adaptabletools.com/docs/reference/cellboxstyle.md).

All the properties are optional, so set only those that differ from the current default in the grid

`CellFontStyle` contains font-related properties and is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [Alignment](https://www.adaptabletools.com/docs/reference/cellfontstyle.md#alignment) | `Alignment` | Align to `Left`, `Right` or `Center` |
| [FontSize](https://www.adaptabletools.com/docs/reference/cellfontstyle.md#fontsize) | `'XSmall' \| 'Small' \| 'Medium' \| 'Large' \| 'XLarge'` | Size of font: `XSmall`, `Small`, `Medium`, `Large` or `XLarge` |
| [FontStyle](https://www.adaptabletools.com/docs/reference/cellfontstyle.md#fontstyle) | `'Normal' \| 'Italic'` | Style of font: `Normal` or `Italic` |
| [FontWeight](https://www.adaptabletools.com/docs/reference/cellfontstyle.md#fontweight) | `'Normal' \| 'Bold'` | Weight of font: `Normal` or `Bold` |
| [ForeColor](https://www.adaptabletools.com/docs/reference/cellfontstyle.md#forecolor) | `string` | Font colour in cell: hex, rgb(a) or name |
| [TextDecoration](https://www.adaptabletools.com/docs/reference/cellfontstyle.md#textdecoration) | `'None' \| 'Underline' \| 'Overline' \| 'LineThrough'` | Decoration of font: `None`, `Underline`, `Overline` or `LineThrough` |

`CellBoxStyle` contains cell-related properties and is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [BackColor](https://www.adaptabletools.com/docs/reference/cellboxstyle.md#backcolor) | `string` | Colour background of cell: hex, rgb(a) or name |
| [BorderColor](https://www.adaptabletools.com/docs/reference/cellboxstyle.md#bordercolor) | `string` | Colour of cell border: hex, rgb(a) or name |
| [BorderRadius](https://www.adaptabletools.com/docs/reference/cellboxstyle.md#borderradius) | `number` | Rounds corners of an element&#39;s outer border edge; equivalent of CSS border-radius |

## Slice Composition

As noted above, `AdaptableStyle` is the union of two reusable interfaces (`CellFontStyle` & `CellBoxStyle`).

For most consumers (Format Column, Quick Search, Flashing Cells, Alerts, Badge Style) you continue to set the full `AdaptableStyle` and the slice split is invisible — same flat object, same wizard.

The slices become visible on **Styled Columns whose renderer paints something other than plain text** — Gradient, Percent Bar, Bullet Chart, Rating, Sparkline, Icon, Range Bar.

In this use case, the styled column accepts one of 2 properties:

- `Font?: CellFontStyle` — when the renderer paints non-text primary content (e.g. a Gradient tint, a Percent Bar) but you still want to control how the value text on top of it is rendered
- `Cell?: CellBoxStyle` — when the renderer paints into the cell content but leaves the cell box alone (e.g. Rating stars, a Sparkline mini-chart) and you want to opt-in to a tinted background or rounded border

The point is so a Styled Column can claim **half** of the style space without inheriting the other half from any [Format Column](https://www.adaptabletools.com/docs/handbook-column-formatting/index.md) on the same column.

- The [wizard](#using-adaptable-style) still edits the whole `AdaptableStyle` for the "full" consumers
- Styled Column wizards present whichever half is meaningful to that styled column
- e.g. the Gradient wizard's **Font** section edits a `CellFontStyle`, the Rating wizard's **Cell** section edits a `CellBoxStyle`

See [Styled Columns Overview](https://www.adaptabletools.com/docs/handbook-styled-column-overview/index.md) for the full slice-based precedence model

## Colour Properties

The colour related properties can be provided in 4 ways:

- Hex Value
- Name of the Colour (which the browser will convert)
- RGB Value
- RGBA Value (if transparency is required)

- When providing colours in [Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md) or API code, you can also reference a theme CSS variable
- e.g. `BackColor: 'var(--ab-color-destructive)'` or `ForeColor: 'var(--ab-color-palette-4)'`

- The value resolves against the active theme at run time, whether the shipped theme or [one customised by you](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md)
- See [Referencing Themes](https://www.adaptabletools.com/docs/handbook-theming-referencing/index.md) for full details on how to do this

**Example: Adaptable Style: Color Picker**

Setting Colours for the AdapTable Style

- In this demo we have set the colours for the [Quick Search Matching Cell Style](https://www.adaptabletools.com/docs/handbook-quick-search-matching-styles/index.md) in 3 different ways:
  - `ForeColor` used Hex value of #765341'
  - `BackColor` used 'hard-coded' value of 'LightGreen'
  - `BorderColor` used rgba value of 245, 245, 245, 1 (though rgb can also be used)
- We also added a BorderRadius of 8 to create a nicer visual effect

- Run different searches and see the style applied

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: 'AdapTable Style Colours',
  initialState: {
    Dashboard: {
      ModuleButtons: ['QuickSearch', 'FormatColumn'],
    },
    Theme: {CurrentTheme: 'dark'},
    QuickSearch: {
      QuickSearchText: 'Java',
      CellMatchStyle: {
        ForeColor: '#765341', // provided Hex
        BackColor: 'LightGreen', // provided name
        BorderColor: 'rgba(245, 245, 245, 1)', // provided rgba value (rgb can also be used)
        BorderRadius: 8
      },
    },
    StatusBar: {
      StatusBars: [
        {
          Key: 'Center Panel',
          StatusBarPanels: ['QuickSearch', 'FormatColumn'],
        },
      ],
    },
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'language',
            'github_stars',
            'license',
            'created_at',
            'has_wiki',
            'updated_at',
            'pushed_at',
            'github_watchers',
            'description',
            'open_issues_count',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
  },
};
```

## Colour Palette

AdapTable displays a Color Picker when users need to select colours in an Adaptable Style.

By default this contains a set of colours that AdapTable provides.

- Customise the default set by overriding `--ab-color-swatch-*`, `--ab-color-palette-*`, and semantic `--ab-color-*` variables on the light and/or dark theme
- See the UI Tutorial on [Providing a Custom Colour Palette](https://www.adaptabletools.com/docs/ui-tutorial-custom-colour-palette/index.md) for more details

## CSS Class Option

The [`AdaptableStyle`](https://www.adaptabletools.com/docs/reference/adaptablestyle.md) object also contains a CSS related property:

| Property | Type | Description |
| --- | --- | --- |
| [ClassName](https://www.adaptabletools.com/docs/reference/adaptablestyle.md#classname) | `string` | CSS class added to the cell. Colour, font and border properties on this object are still applied. |

The [`ClassName`](https://www.adaptabletools.com/docs/reference/adaptablestyle.md#classname) property references an pre-existing CSS style class which, when specified, is applied to the corresponding grid cell in AG Grid.

Make sure that the referenced CSS Class is provided with your application

This CSS Class is one that is included in the css for the application.

### `styleClassNames`

CSS Class names available when creating an Adaptable Style

Names listed here appear in Settings Panel wizards so run-time users can pick a Class instead of building a Style property by property. The classes themselves still need to be in the application stylesheet.

```ts {3}
userInterfaceOptions: {
  styleClassNames: ['boldBrownStyle', 'darkGreenStyle', 'darkRedStyle'],
},
```

The following steps are required:

### Providing CSS Class Names to an Adaptable Style

These are the steps involved:

The CSS class definitions have to be available at runtime, so should be included in the stylesheets provided to the application

```css [[1, 2, "darkGreenStyle"], [1, 5, "darkRedStyle"], [1, 8, "boldBrownStyle"]]
// CSS file
.darkGreenStyle {
  color: darkgreen !important;
}
.darkRedStyle {
  color: darkred !important;
}
.boldBrownStyle {
  color: brown;
  font-weight: bolder !important;
}
```

Items included in `styleClassNames` (see above) are available at run-time.

They appear in AdapTable UI wizards and can be selected when creating or editing Adaptable Objects.

```ts [[2, 3, "styleClassNames"]]
const adaptableOptions: AdaptableOptions = {
  userInterfaceOptions: {
    styleClassNames: ['boldBrownStyle', 'darkGreenStyle', 'darkRedStyle'],
  },
};
```

In addition the `ClassName` can be provided at design-time through [Initial Adaptable State](https://www.adaptabletools.com/docs/dev-guide-adaptable-state-initial-state/index.md).

This will be applied automatically by AdapTable to the relevant objects and Modules.

```ts [[3, 4, "ClassName"], [3, 11, "ClassName"], [3, 17, "ClassName"]]
const adaptableOptions: AdaptableOptions = {
  initialState: {
    QuickSearch: {
      Style: {ClassName: 'boldBrownStyle'},
    },
    FormatColumn: {
      FormatColumns: [
        {
          Name: 'FormatColumn-number-206',
          Scope: {DataTypes: ['number']},
          Style: {ClassName: 'darkGreenStyle'},
          Rule: '$SCOPE > 0',
        },
        {
          Name: 'FormatColumn-number-207',
          Scope: {DataTypes: ['number']},
          Style: {ClassName: 'darkRedStyle'},
          Rule: '$SCOPE < 0',
        },
      ],
    },
  },
};
```

### FAQ

**Can I provide transparency to the colour?**
Yes — use rgba (or opacity properties where the wizard exposes them), for example:

```json
BackColor: "rgba(255, 255, 224, 0.3)"
```
