# Rating Style

Canonical page: https://www.adaptabletools.com/docs/handbook-styled-column-rating

- The Rating Styled Column renders each cell of a **numeric** column as a row of small icons (e.g. ★★★☆☆) 
- The fill represents the cell value on a `0..Max` scale
- Comes with four built-in icon shapes: `Star`, `Heart`, `Circle`, `Thumb`
- Supports partial (half-)icon fills for fractional values, and an optional numeric label

The Rating Styled Column turns a **numeric** column into a familiar “score out of N” visual.

Each cell shows `Max` icons; the filled portion reflects the cell value.

Like all Styled Columns, the Rating Style provides a powerful visual without needing to build a custom cell renderer

The Rating Style is a compact, instantly legible style — useful for review scores, satisfaction ratings, risk levels, performance bands, or any column where the numeric value sits on a small ordinal scale.

- Rating Column Styles apply to **scalar numeric columns** only

### Rating vs Bullet Chart vs Range Bar: Which Styled Column should I use?

In addition to the Rating Style, AdapTable provides 2 similar Styled Columns: Bullet Chart and Range Bar.

All three styles communicate where a value sits on a numeric scale, but they answer slightly different questions:

|                    | Rating Column                    | Bullet Chart                                         | Range Bar                                      |
| ------------------ | -------------------------------- | ---------------------------------------------------- | ---------------------------------------------- |
| Primary question   | "what's the score out of N?"     | "how does this value compare to a target and bands?" | "where does this value sit between Min & Max?" |
| Scale endpoints    | `0..Max` (whole-icon resolution) | `CellRanges` (or column min/max)                     | `Min` / `Max` (numbers, columns or aggregates) |
| Comparative marker | implicit (filled vs empty icons) | first-class `TargetProperties` (and per-row targets) | optional `Reference` (with marker)             |
| Best for           | review-style ordinal scales      | KPIs with a defined target and qualitative bands     | values on a quantitative interval              |

## Anatomy

A Rating cell consists of 4 elements:

- A horizontal row of **icons** (all the same shape)
- A **filled** portion (left → right) representing the cell value
- An **empty** portion (the remaining icons) drawn as a subtle background, so the maximum is always visible
- Optionally, the formatted cell value rendered alongside the icons

- The cell value is interpreted in the **same numeric units as `Max`** (which sets number of icons), i.e. it is not scaled
- For example, with `Max: 5` and a cell value of `4`, the renderer draws roughly four filled stars

To map a 0–10 score onto five icons, either set `Max: 10` (10 icons) or pre-divide via a [Calculated Column](https://www.adaptabletools.com/docs/handbook-calculated-column/index.md) (`value / 2`)

**Example: Rating Style: Showcase**

Three Rating Styles side-by-side, each with a different icon, colour and scale

- **Product Rating** — classic **Star** out of `5` with `AllowHalf: true` and the numeric value shown alongside
- **Satisfaction** — **Heart** out of `5` in pink with `AllowHalf: false`
- **Would Recommend** — **Thumb** out of `3` in green, value shown alongside
- Non-rating columns (`name`, `language`) sit between the rating columns as visual separators
- Each icon shape, fill / empty colour, scale and label option is explained in the sections below

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

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts
  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 {ProductReview} from './rowData';

export const adaptableOptions: AdaptableOptions<ProductReview> = {
  primaryKey: 'id',
  adaptableId: 'Rating Style Showcase',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: [
            'name',
            'productRating',
            'language',
            'satisfaction',
            'wouldRecommend',
          ],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'productRating',
          Name: 'Product rating stars',
          RatingStyle: {
            Icon: 'Star',
            Max: 5,
            Size: 16,
            Gap: 2,
            AllowHalf: true,
            ShowValue: true,
            ToolTipText: ['CellValue', 'PercentageValue'],
          },
        },
        {
          ColumnId: 'satisfaction',
          Name: 'Satisfaction hearts',
          RatingStyle: {
            Icon: 'Heart',
            Max: 5,
            Size: 18,
            Gap: 3,
            FilledColor: '#e91e63',
            EmptyColor: 'color-mix(in srgb, currentColor 20%, transparent)',
            AllowHalf: false,
          },
        },
        {
          ColumnId: 'wouldRecommend',
          Name: 'Would Recommend thumbs',
          RatingStyle: {
            Icon: 'Thumb',
            Max: 3,
            Size: 20,
            Gap: 4,
            FilledColor: '#28a745',
            EmptyColor: 'color-mix(in srgb, currentColor 18%, transparent)',
            AllowHalf: false,
            ShowValue: true,
          },
        },
      ],
    },
  },
};
```
**`src/rowData.ts`**

```ts
export interface ProductReview {
  id: number;
  name: string;
  language: string;
  productRating: number;
  productRatingRounded: number;
  satisfaction: number;
  experienceScore: number;
  wouldRecommend: number;
}

export const rowData: ProductReview[] = [
  {
    id: 1,
    name: 'react',
    language: 'JavaScript',
    productRating: 4.5,
    productRatingRounded: 4.5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 2,
    name: 'angular',
    language: 'TypeScript',
    productRating: 3.5,
    productRatingRounded: 3.5,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 2,
  },
  {
    id: 3,
    name: 'vue',
    language: 'JavaScript',
    productRating: 4.2,
    productRatingRounded: 4.2,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 3,
  },
  {
    id: 4,
    name: 'svelte',
    language: 'JavaScript',
    productRating: 2.8,
    productRatingRounded: 2.8,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 1,
  },
  {
    id: 5,
    name: 'ember',
    language: 'JavaScript',
    productRating: 1.5,
    productRatingRounded: 1.5,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 0,
  },
  {
    id: 6,
    name: 'backbone',
    language: 'JavaScript',
    productRating: 0,
    productRatingRounded: 0,
    satisfaction: 1,
    experienceScore: 1,
    wouldRecommend: 0,
  },
  {
    id: 7,
    name: 'meteor',
    language: 'JavaScript',
    productRating: 5,
    productRatingRounded: 5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 8,
    name: 'aurelia',
    language: 'TypeScript',
    productRating: 3.2,
    productRatingRounded: 3.2,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 2,
  },
  {
    id: 9,
    name: 'knockout',
    language: 'JavaScript',
    productRating: 2.2,
    productRatingRounded: 2.2,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 1,
  },
  {
    id: 10,
    name: 'dojo',
    language: 'JavaScript',
    productRating: 4.8,
    productRatingRounded: 4.8,
    satisfaction: 4,
    experienceScore: 5,
    wouldRecommend: 3,
  },
];
```
**`src/columnDefs.ts`**

```ts
import {ColDef} from 'ag-grid-enterprise';
import {ProductReview} from './rowData';

export const columnDefs: ColDef<ProductReview>[] = [
  {field: 'id', hide: true, cellDataType: 'number'},
  {field: 'name', headerName: 'Product', cellDataType: 'text'},
  {field: 'productRating', headerName: 'Rating', cellDataType: 'number'},
  {field: 'language', headerName: 'Language', cellDataType: 'text'},
  {field: 'satisfaction', headerName: 'Satisfaction', cellDataType: 'number'},
  {
    field: 'wouldRecommend',
    headerName: 'Would Recommend',
    cellDataType: 'number',
  },
];
```

## Rating Icon

The Icon displayed in the Rating Style is highly configurable.

### Icon Shapes

The `Icon` property selects which glyph is repeated across the row.

AdapTable provides 4 possible shapes for the Icon:

| Value              | Description       | Typically Used                       |
| ------------------ | ----------------- | ------------------------------------ |
| `'Star'` (default) | Five-pointed star | generic ratings                      |
| `'Heart'`          | Rounded heart     | wishlist / like-style ratings        |
| `'Circle'`         | Filled circle     | Apple/iOS scoring style              |
| `'Thumb'`          | Thumbs-up         | binary-ish ratings (thumbs-up count) |

#### Star (default)

The default **Star** shape with `Max: 5` is the usual choice for review-style scores out of five.

**Example: Rating Style: Stars**

Stars with half icons, value label and tooltip

- **Product Rating** — `Icon: 'Star'`, `Max: 5`, `AllowHalf: true` (e.g. `3.5` shows three full stars and one half-filled)
- **Show Value** and tooltip with cell value and **percentage of Max** enabled
- Includes a `0` row (empty stars) and values above `5` (fully filled)

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

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts
  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 {ProductReview} from './rowData';

export const adaptableOptions: AdaptableOptions<ProductReview> = {
  primaryKey: 'id',
  adaptableId: 'Rating Style Default',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: ['name', 'productRating', 'language'],
          ColumnSorts: [{ColumnId: 'productRating', SortOrder: 'Desc'}],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'productRating',
          Name: 'Product Rating stars',
          RatingStyle: {
            Icon: 'Star',
            Max: 5,
            Size: 16,
            Gap: 2,
            AllowHalf: true,
            ShowValue: true,
            ToolTipText: ['CellValue', 'PercentageValue'],
          },
        },
      ],
    },
  },
};
```
**`src/columnDefs.ts`**

```ts
import {ColDef} from 'ag-grid-enterprise';
import {ProductReview} from './rowData';

export const columnDefs: ColDef<ProductReview>[] = [
  {field: 'id', hide: true, cellDataType: 'number'},
  {field: 'name', headerName: 'Product', cellDataType: 'text'},
  {
    field: 'productRating',
    headerName: 'Product Rating',
    cellDataType: 'number',
  },
  {field: 'language', cellDataType: 'text'},
];
```
**`src/rowData.ts`**

```ts
export interface ProductReview {
  id: number;
  name: string;
  language: string;
  productRating: number;
  productRatingRounded: number;
  satisfaction: number;
  experienceScore: number;
  wouldRecommend: number;
}

export const rowData: ProductReview[] = [
  {
    id: 1,
    name: 'react',
    language: 'JavaScript',
    productRating: 4.5,
    productRatingRounded: 4.5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 2,
    name: 'angular',
    language: 'TypeScript',
    productRating: 3.5,
    productRatingRounded: 3.5,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 2,
  },
  {
    id: 3,
    name: 'vue',
    language: 'JavaScript',
    productRating: 4.2,
    productRatingRounded: 4.2,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 3,
  },
  {
    id: 4,
    name: 'svelte',
    language: 'JavaScript',
    productRating: 2.8,
    productRatingRounded: 2.8,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 1,
  },
  {
    id: 5,
    name: 'ember',
    language: 'JavaScript',
    productRating: 1.5,
    productRatingRounded: 1.5,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 0,
  },
  {
    id: 6,
    name: 'backbone',
    language: 'JavaScript',
    productRating: 0,
    productRatingRounded: 0,
    satisfaction: 1,
    experienceScore: 1,
    wouldRecommend: 0,
  },
  {
    id: 7,
    name: 'meteor',
    language: 'JavaScript',
    productRating: 5,
    productRatingRounded: 5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 8,
    name: 'aurelia',
    language: 'TypeScript',
    productRating: 3.2,
    productRatingRounded: 3.2,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 2,
  },
  {
    id: 9,
    name: 'knockout',
    language: 'JavaScript',
    productRating: 2.2,
    productRatingRounded: 2.2,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 1,
  },
  {
    id: 10,
    name: 'dojo',
    language: 'JavaScript',
    productRating: 4.8,
    productRatingRounded: 4.8,
    satisfaction: 4,
    experienceScore: 5,
    wouldRecommend: 3,
  },
];
```

#### Other shapes

Besides **Star**, AdapTable provides **`Heart`**, **`Circle`** and **`Thumb`** — the same `RatingStyle` API applies; only `Icon` (and usually `Max`) change.

- **`Heart`** — use when the rating should read more like a “like” or satisfaction score than a generic star row
- **`Circle`** — use for a compact dot row (often seen in app-store / iOS-style scores); supports half fills like stars

**Example: Rating Style: Other Shapes**

Heart and Circle icon shapes

- **Satisfaction** — `Icon: 'Heart'`, `Max: 5`, whole icons only, pink filled / faded empty colours
- **Experience** — `Icon: 'Circle'`, `Max: 5`, `AllowHalf: true` (blue dots), same numeric scale as satisfaction

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

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts
  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 {ProductReview} from './rowData';

export const adaptableOptions: AdaptableOptions<ProductReview> = {
  primaryKey: 'id',
  adaptableId: 'Rating Other Icon Shapes',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: ['name', 'satisfaction', 'experienceScore', 'language'],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'satisfaction',
          Name: 'Satisfaction hearts',
          RatingStyle: {
            Icon: 'Heart',
            Max: 5,
            Size: 18,
            Gap: 3,
            FilledColor: '#e91e63',
            EmptyColor: 'color-mix(in srgb, currentColor 20%, transparent)',
            AllowHalf: false,
          },
        },
        {
          ColumnId: 'experienceScore',
          Name: 'Experience circles',
          RatingStyle: {
            Icon: 'Circle',
            Max: 5,
            Size: 14,
            Gap: 4,
            FilledColor: '#007aff',
            EmptyColor: 'color-mix(in srgb, currentColor 18%, transparent)',
            AllowHalf: true,
          },
        },
      ],
    },
  },
};
```
**`src/columnDefs.ts`**

```ts
import {ColDef} from 'ag-grid-enterprise';
import {ProductReview} from './rowData';

export const columnDefs: ColDef<ProductReview>[] = [
  {field: 'id', hide: true, cellDataType: 'number'},
  {field: 'name', headerName: 'Product', cellDataType: 'text'},
  {
    field: 'satisfaction',
    headerName: 'Satisfaction',
    cellDataType: 'number',
  },
  {
    field: 'experienceScore',
    headerName: 'Experience',
    cellDataType: 'number',
  },
  {field: 'language', cellDataType: 'text'},
];
```
**`src/rowData.ts`**

```ts
export interface ProductReview {
  id: number;
  name: string;
  language: string;
  productRating: number;
  productRatingRounded: number;
  satisfaction: number;
  experienceScore: number;
  wouldRecommend: number;
}

export const rowData: ProductReview[] = [
  {
    id: 1,
    name: 'react',
    language: 'JavaScript',
    productRating: 4.5,
    productRatingRounded: 4.5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 2,
    name: 'angular',
    language: 'TypeScript',
    productRating: 3.5,
    productRatingRounded: 3.5,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 2,
  },
  {
    id: 3,
    name: 'vue',
    language: 'JavaScript',
    productRating: 4.2,
    productRatingRounded: 4.2,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 3,
  },
  {
    id: 4,
    name: 'svelte',
    language: 'JavaScript',
    productRating: 2.8,
    productRatingRounded: 2.8,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 1,
  },
  {
    id: 5,
    name: 'ember',
    language: 'JavaScript',
    productRating: 1.5,
    productRatingRounded: 1.5,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 0,
  },
  {
    id: 6,
    name: 'backbone',
    language: 'JavaScript',
    productRating: 0,
    productRatingRounded: 0,
    satisfaction: 1,
    experienceScore: 1,
    wouldRecommend: 0,
  },
  {
    id: 7,
    name: 'meteor',
    language: 'JavaScript',
    productRating: 5,
    productRatingRounded: 5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 8,
    name: 'aurelia',
    language: 'TypeScript',
    productRating: 3.2,
    productRatingRounded: 3.2,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 2,
  },
  {
    id: 9,
    name: 'knockout',
    language: 'JavaScript',
    productRating: 2.2,
    productRatingRounded: 2.2,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 1,
  },
  {
    id: 10,
    name: 'dojo',
    language: 'JavaScript',
    productRating: 4.8,
    productRatingRounded: 4.8,
    satisfaction: 4,
    experienceScore: 5,
    wouldRecommend: 3,
  },
];
```

### Filled and Empty Colours

Users are able to configure the colour for both filled and empty icons, using 2 properties:

| Property      | Default Value                                                                                                         |
| ------------- | --------------------------------------------------------------------------------------------------------------------- |
| `FilledColor` | Theme's warm amber (`var(--ab-color-warn, #f5a623)`)                                                                  |
| `EmptyColor`  | Low-opacity tint of the current text colour, so the empty icons remain visible without competing with the filled ones |

- Both these properties can accept any CSS colour, including [CSS variables](https://www.adaptabletools.com/docs/handbook-theming-custom/index.md)
- Using `var(--ab-color-…)` makes the Rating follow the active Theme

### Partial (Half) Icons

AdapTable allows you to configure how fractional values are rendered in the Ratings Style.

This is done via the `AllowHalf` boolean property:

| Value            | Description                                                                           | How it Renders 3.5 out of 5                      |
| ---------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `true` (default) | Decimal part fills a fraction of the next icon                                        | 3 full icons + 1 half-filled + 1 empty           |
| `false`          | Clamped value is rounded with `Math.round` before drawing, so only whole icons appear | 4 full icons + 1 empty (`Math.round(3.5)` → `4`) |

Half-icon rendering looks crisp at any `Size` because the renderer uses an SVG clip rather than an opacity trick

**Example: Rating Style: Allow Half**

Half icons vs rounded whole icons

- This demo uses two columns with identical values and config (`Max: 5`, stars, value shown beside icons) to illustrate rounding vs partial fill:
  - **Half icons** — `AllowHalf: true` (`3.5` → three full + one half + one empty)
  - **Whole icons** — `AllowHalf: false` (`3.5` → four full + one empty)

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

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts
  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 {ProductReview} from './rowData';

export const adaptableOptions: AdaptableOptions<ProductReview> = {
  primaryKey: 'id',
  adaptableId: 'Rating Allow Half',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: ['name', 'productRating', 'productRatingRounded'],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'productRating',
          Name: 'AllowHalf true',
          RatingStyle: {
            Icon: 'Star',
            Max: 5,
            Size: 16,
            Gap: 2,
            AllowHalf: true,
            ShowValue: true,
          },
        },
        {
          ColumnId: 'productRatingRounded',
          Name: 'AllowHalf false',
          RatingStyle: {
            Icon: 'Star',
            Max: 5,
            Size: 16,
            Gap: 2,
            AllowHalf: false,
            ShowValue: true,
          },
        },
      ],
    },
  },
};
```
**`src/columnDefs.ts`**

```ts
import {ColDef} from 'ag-grid-enterprise';
import {ProductReview} from './rowData';

export const columnDefs: ColDef<ProductReview>[] = [
  {field: 'id', hide: true, cellDataType: 'number'},
  {field: 'name', headerName: 'Product', cellDataType: 'text'},
  {
    field: 'productRating',
    headerName: 'Half icons',
    cellDataType: 'number',
  },
  {
    field: 'productRatingRounded',
    headerName: 'Whole icons',
    cellDataType: 'number',
  },
];
```
**`src/rowData.ts`**

```ts
export interface ProductReview {
  id: number;
  name: string;
  language: string;
  productRating: number;
  productRatingRounded: number;
  satisfaction: number;
  experienceScore: number;
  wouldRecommend: number;
}

export const rowData: ProductReview[] = [
  {
    id: 1,
    name: 'react',
    language: 'JavaScript',
    productRating: 4.5,
    productRatingRounded: 4.5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 2,
    name: 'angular',
    language: 'TypeScript',
    productRating: 3.5,
    productRatingRounded: 3.5,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 2,
  },
  {
    id: 3,
    name: 'vue',
    language: 'JavaScript',
    productRating: 4.2,
    productRatingRounded: 4.2,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 3,
  },
  {
    id: 4,
    name: 'svelte',
    language: 'JavaScript',
    productRating: 2.8,
    productRatingRounded: 2.8,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 1,
  },
  {
    id: 5,
    name: 'ember',
    language: 'JavaScript',
    productRating: 1.5,
    productRatingRounded: 1.5,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 0,
  },
  {
    id: 6,
    name: 'backbone',
    language: 'JavaScript',
    productRating: 0,
    productRatingRounded: 0,
    satisfaction: 1,
    experienceScore: 1,
    wouldRecommend: 0,
  },
  {
    id: 7,
    name: 'meteor',
    language: 'JavaScript',
    productRating: 5,
    productRatingRounded: 5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 8,
    name: 'aurelia',
    language: 'TypeScript',
    productRating: 3.2,
    productRatingRounded: 3.2,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 2,
  },
  {
    id: 9,
    name: 'knockout',
    language: 'JavaScript',
    productRating: 2.2,
    productRatingRounded: 2.2,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 1,
  },
  {
    id: 10,
    name: 'dojo',
    language: 'JavaScript',
    productRating: 4.8,
    productRatingRounded: 4.8,
    satisfaction: 4,
    experienceScore: 5,
    wouldRecommend: 3,
  },
];
```

## Rating Cell

Like with other Styled Columns, its possible to configure how to render the Cell that contains the Rating Icon.

### Cell Style

The cell behind the icons is fully styleable (back colour, border, border radius, etc.) using the `Cell` property.

When set, the Cell slice **takes precedence** over any matching [Format Column](https://www.adaptabletools.com/docs/handbook-column-formatting/index.md) for these properties

**Example: Rating Style: Cell Style**

Showing Rating Style with cell box styling using Thumbs up

- This example shows how to style the cell containing a Rating Style (for which we use the `Thumbs up` Shape)
- The **`Cell`** — has a light green background and dark green border to match the icon row which has a dark green fill and a white partial fill
- We also configure the Style to show the Cell Value

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

```text
src/
  adaptableOptions.ts
  agGridModules.ts     [template]
  columnDefs.ts
  gridOptions.ts       [template]
  index.ts             [template]
  onAdaptableReady.ts  [template]
  rowData.ts
  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 {ProductReview} from './rowData';

export const adaptableOptions: AdaptableOptions<ProductReview> = {
  primaryKey: 'id',
  adaptableId: 'Rating Cell Style',
  initialState: {
    Dashboard: {
      ModuleButtons: ['StyledColumn'],
    },
    Theme: {CurrentTheme: 'dark'},
    Layout: {
      CurrentLayout: 'Standard Layout',
      Layouts: [
        {
          Name: 'Standard Layout',
          TableColumns: ['name', 'wouldRecommend', 'language'],
          AutoSizeColumns: true,
        },
      ],
    },
    StyledColumn: {
      StyledColumns: [
        {
          ColumnId: 'wouldRecommend',
          Name: 'Would Recommend thumbs',
          RatingStyle: {
            Icon: 'Thumb',
            Max: 3,
            Size: 20,
            Gap: 4,
            FilledColor: '#28a745',
            EmptyColor: 'white',
            AllowHalf: false,
            ShowValue: true,
            ToolTipText: ['PercentageValue'],
            Cell: {
              BackColor: 'var(--ab-color-palette-6)',
              BorderColor: 'rgba(40, 167, 69, 0.35)',
              BorderRadius: 6,
            },
          },
        },
      ],
    },
  },
};
```
**`src/columnDefs.ts`**

```ts
import {ColDef} from 'ag-grid-enterprise';
import {ProductReview} from './rowData';

export const columnDefs: ColDef<ProductReview>[] = [
  {field: 'id', hide: true, cellDataType: 'number'},
  {field: 'name', headerName: 'Product', cellDataType: 'text'},
  {
    field: 'wouldRecommend',
    headerName: 'Would Recommend',
    cellDataType: 'number',
  },
  {field: 'language', cellDataType: 'text'},
];
```
**`src/rowData.ts`**

```ts
export interface ProductReview {
  id: number;
  name: string;
  language: string;
  productRating: number;
  productRatingRounded: number;
  satisfaction: number;
  experienceScore: number;
  wouldRecommend: number;
}

export const rowData: ProductReview[] = [
  {
    id: 1,
    name: 'react',
    language: 'JavaScript',
    productRating: 4.5,
    productRatingRounded: 4.5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 2,
    name: 'angular',
    language: 'TypeScript',
    productRating: 3.5,
    productRatingRounded: 3.5,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 2,
  },
  {
    id: 3,
    name: 'vue',
    language: 'JavaScript',
    productRating: 4.2,
    productRatingRounded: 4.2,
    satisfaction: 4,
    experienceScore: 4,
    wouldRecommend: 3,
  },
  {
    id: 4,
    name: 'svelte',
    language: 'JavaScript',
    productRating: 2.8,
    productRatingRounded: 2.8,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 1,
  },
  {
    id: 5,
    name: 'ember',
    language: 'JavaScript',
    productRating: 1.5,
    productRatingRounded: 1.5,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 0,
  },
  {
    id: 6,
    name: 'backbone',
    language: 'JavaScript',
    productRating: 0,
    productRatingRounded: 0,
    satisfaction: 1,
    experienceScore: 1,
    wouldRecommend: 0,
  },
  {
    id: 7,
    name: 'meteor',
    language: 'JavaScript',
    productRating: 5,
    productRatingRounded: 5,
    satisfaction: 5,
    experienceScore: 5,
    wouldRecommend: 3,
  },
  {
    id: 8,
    name: 'aurelia',
    language: 'TypeScript',
    productRating: 3.2,
    productRatingRounded: 3.2,
    satisfaction: 3,
    experienceScore: 3,
    wouldRecommend: 2,
  },
  {
    id: 9,
    name: 'knockout',
    language: 'JavaScript',
    productRating: 2.2,
    productRatingRounded: 2.2,
    satisfaction: 2,
    experienceScore: 2,
    wouldRecommend: 1,
  },
  {
    id: 10,
    name: 'dojo',
    language: 'JavaScript',
    productRating: 4.8,
    productRatingRounded: 4.8,
    satisfaction: 4,
    experienceScore: 5,
    wouldRecommend: 3,
  },
];
```

### Cell Value

It is possible to render the (numeric) cell value next to the icons (e.g. `★★★★☆ 4`).

This is done by setting the `ShowValue` property to `true`.

The label uses the grid’s **`formatValue`** when AG Grid supplies it, otherwise `String(value)`

### Tooltip

The `ToolTipText` property controls the AG Grid cell tooltip (similar to other numeric Styled Columns).

You can configure whether to show the Cell's value, a percentage (or both):

| Token               | Content                                                                   |
| ------------------- | ------------------------------------------------------------------------- |
| `'CellValue'`       | The cell value as a string                                                |
| `'PercentageValue'` | The cell value as a whole-number percent (e.g. `4` with `Max: 5` → `80%`) |

- When both properties are enabled, they appear as `4 (80%)`
- This is **not** the column min/max percentage used by Gradient or Percent Bar — it is always relative to **`Max`**

## Empty Cells

AdapTable deals with blank, zero and invalid cells in specific ways as follows:

| Cell value                         | What renders                                              |
| ---------------------------------- | --------------------------------------------------------- |
| `null` / `undefined` / non-numeric | **Nothing** — no icons (not the same as a zero rating)    |
| `0` (or negative, clamped to `0`)  | A full row of **empty** icons (`Max` glyphs, none filled) |
| `1..Max`                           | Filled icons per value (with optional half-icon fill)     |
| Above `Max`                        | Fully filled row                                          |

## Row Scope

Users can decide which kinds of Rows will include the Rating Style.

See  [Styled Column Row Scope](https://www.adaptabletools.com/docs/handbook-styled-column-overview/index.md#row-scope) for details of the types of Rows which can be included / excluded from a Styled Column

If the current row is **excluded** (e.g. no Group rows) but the cell has a value, the Grid shows that value as plain text

## Defining Rating Styles

Rating Styled Columns are defined as part of the Styled Column Initial State.

### Providing a Rating Style in Styled Column State

Each Styled Column needs a `ColumnId`, a `Name`, and a `RatingStyle` object.

The example below defines **two** numeric columns so you can see different shapes and options side by side.

Configure 2 properties:
- `Icon` - the shape to use
- `Max` - icon count and the rating cap (in **same units** as cell value)

Set 2 properties
- `Size` (default 14)
- `Gap`  -space between icons (default 2)

- Set 2 colours - (`FilledColor` / `EmptyColor` - via CSS variables for coloured and empty icons
- Set `AllowHalf` to fill half icons (so `3.5` renders a half-filled star)

Set `ShowValue` to `true` to show the Cell Value beside Icons.

This is the formatted value (e.g. `★★★★☆ 4.2`)

Use `ToolTipText` to choose whether to display a Tooltip:

Choose whether to see `CellValue` `PercentageValue` or both.

Configure the  `Cell` property to style the Cell that contains the Icons.

This overrides any styling provided in Format Column.

```js [[1, 5, "Name"], [1, 6, "ColumnId"], [1, 7, "RatingStyle"], [1, 20, "Name"], [1, 21, "ColumnId"], [1, 22, "RatingStyle"], [2, 8, "Icon"], [2, 9, "Max"], [2, 23, "Icon"], [2, 24, "Max"], [3, 10, "Size"], [3, 11, "Gap"], [3, 25, "Size"], [3, 26, "Gap"], [4, 12, "FilledColor"], [4, 13, "EmptyColor"], [4, 14, "AllowHalf"], [4, 27, "FilledColor"], [4, 28, "EmptyColor"], [4, 29, "AllowHalf"], [5, 15, "ShowValue"], [5, 30, "ShowValue"], [6, 16, "ToolTipText"], [6, 31, "ToolTipText"], [7, 32, "Cell"]]
const initialState: InitialState = {
  StyledColumn: {
    StyledColumns: [
      {
        Name: 'Customer Score',
        ColumnId: 'customerScore',
        RatingStyle: {
          Icon: 'Star',
          Max: 5,
          Size: 16,
          Gap: 2,
          FilledColor: 'var(--ab-color-warn, #f5a623)',
          EmptyColor: 'color-mix(in srgb, currentColor 22%, transparent)',
          AllowHalf: true,
          ShowValue: true,
          ToolTipText: ['CellValue', 'PercentageValue'],
        },
      },
      {
        Name: 'Would Recommend',
        ColumnId: 'wouldRecommend',
        RatingStyle: {
          Icon: 'Thumb',
          Max: 3,
          Size: 20,
          Gap: 4,
          FilledColor: '#28a745',
          EmptyColor: 'rgba(0, 0, 0, 0.12)',
          AllowHalf: false,
          ShowValue: false,
          ToolTipText: ['PercentageValue'],
          Cell: {
            BackColor: 'var(--ab-color-primary-light, #e8f4fc)',
            BorderRadius: '4px',
          },
        },
      },
    ],
  },
};
```

## Creating Rating Styles

Rating Styled Columns can be created at run-time using the Styled Column UI Wizard from:

- the **Styled Column** section in the [Settings Panel](https://www.adaptabletools.com/docs/ui-settings-panel/index.md) 
- **Create Rating Column** / **Edit Rating Style** in the [Column Menu](https://www.adaptabletools.com/docs/ui-column-menu/index.md) on a **numeric** column

### Creating a Rating Column Style using the Styled Column Wizard

The Wizard guides you through the following steps:

In the **Settings** step:

- Enter a **Name** for the Styled Column (must be unique within the Grid)
- Pick **Rating** from the list of Styled Column Types (the wizard header becomes **Rating Column**)

The **Scope** step is shared by every Styled Column. Use it to:

- Pick the **Column** to rate — only **numeric** columns without an existing Styled Column are listed
- Choose which **row kinds** the rating renders on: **Data**, **Group**, **Summary** and **Total**

By default **Data**, **Summary** and **Total** are included, and **Group** rows are excluded — see [Row scope](#row-scope).

The **Style** step is a single screen with a **live preview** (sample value ≈ 70% of **Max**) that updates as you edit. Until a column is chosen in **Scope**, the step prompts you to select a column first.

The step is organised into three cards:

- **Icon**
  - **Max** — number of icons drawn and the rating cap (same units as the cell value; no auto-scaling). Leave blank to use the default (`5`). Must be a positive whole number when set.
  - **Icon** — `Star`, `Heart`, `Circle` or `Thumb`
  - **Filled Colour** / **Empty Colour** — theme-aware colour pickers (defaults match the renderer’s amber fill and faded empty icons)
  - **Icon Size (px)** — square size of each icon (minimum `4`; default `14`)
  - **Icon Gap (px)** — space between adjacent icons (default `2`)
  - **Allow Half Icons** — when on (default), fractional values fill part of the next icon; when off, values are rounded to whole icons

- **Text**
  - **Show Value** — when on, displays the formatted cell value beside the icon row
  - **Tooltip** — **Cell Value** and/or **Percentage Value** (value ÷ `Max`; see [Tooltip](#tooltip))

- **Cell** — optional **box** styling (background, border, border radius, etc.) behind the rating; where set, overrides matching [Format Column](https://www.adaptabletools.com/docs/handbook-column-formatting/index.md) cell-box properties

Two further wizard steps — **Tags** (when the workspace has tags enabled) and **Summary** (a read-only review of every previous step, including the live rating preview) — are shared by all AdapTable modules and not specific to Rating Columns.

### FAQ

**Can a Rating Column show fractional values?**
Yes. With `AllowHalf: true` (the default) the renderer fills a fraction of the next icon. 
Set `AllowHalf: false` to round to whole icons.

**Can I use the Rating Style on a 0–10 score that should still show five stars?**
Yes, but the value is interpreted in the same units as `Max`. 
Either keep `Max: 10` (ten icons), or pre-scale via a Calculated Column (`value / 2`).

**What is the difference between an empty cell and a zero rating?**
An empty or non-numeric cell renders **nothing**. 
A numeric **`0`** renders **`Max` empty icons** — the scale is visible but unfilled.

**Why do I see plain text on Group rows instead of stars?**
Those row kinds are excluded in **Scope**. 
When the rating renderer does not apply, the cell shows **`String(value)`** as plain text. See [Row scope](#row-scope).

**Can I change the cell background behind the icons?**
Yes — set `RatingStyle.Cell.BackColor` (or border / border radius). 
The Cell slice takes precedence over any Format Column for those properties.

**Why does the rating stay coloured in dark mode?**
The defaults use CSS variables (`var(--ab-color-warn, …)` with faded `currentColor` tint) that follow Current Theme. 
Set explicit colours on `FilledColor` / `EmptyColor` if you want pixel-exact control.

**What happens if the Styled Column is suspended?**
When `IsSuspended` is `true`, AdapTable stops using the rating renderer for that column.