# Layout Technical Reference

Canonical page: https://www.adaptabletools.com/docs/technical-reference-layouts

## Layout State

| Property | Type | Description |
| --- | --- | --- |
| [CurrentLayout](https://www.adaptabletools.com/docs/reference/layoutstate.md#currentlayout) | `string` | Layout to be loaded when AdapTable starts (using `Name` property in Layout); if not provided the first Layout is used |
| [LayoutExtensions](https://www.adaptabletools.com/docs/reference/layoutstate.md#layoutextensions) | [`LayoutExtension`](https://www.adaptabletools.com/docs/reference/layoutextension.md)`[]` | Objects from other Modules (e.g. Format Columns, Styled Columns) which apply only in specific Layouts |
| [Layouts](https://www.adaptabletools.com/docs/reference/layoutstate.md#layouts) | [`LayoutArray`](https://www.adaptabletools.com/docs/reference/layoutarray.md) | Collection of Layouts - can be Table or Pivot |

### Layout Extensions

| Property | Type | Description |
| --- | --- | --- |
| [Alert](https://www.adaptabletools.com/docs/reference/layoutextension.md#alert) | `string[]` | Names of Alert Definitions which apply in this Layout |
| [CustomSort](https://www.adaptabletools.com/docs/reference/layoutextension.md#customsort) | `string[]` | Names of Custom Sorts which apply in this Layout |
| [FlashingCell](https://www.adaptabletools.com/docs/reference/layoutextension.md#flashingcell) | `string[]` | Names of Flashing Cell Definitions which apply in this Layout |
| [FormatColumn](https://www.adaptabletools.com/docs/reference/layoutextension.md#formatcolumn) | `string[]` | Names of Format Columns which apply in this Layout |
| [LayoutName](https://www.adaptabletools.com/docs/reference/layoutextension.md#layoutname) | `string` | Name of the Layout being extended (Mandatory) |
| [PlusMinus](https://www.adaptabletools.com/docs/reference/layoutextension.md#plusminus) | `string[]` | Names of Plus Minus Nudges which apply in this Layout |
| [Shortcut](https://www.adaptabletools.com/docs/reference/layoutextension.md#shortcut) | `string[]` | Names of Shortcuts which apply in this Layout |
| [StyledColumn](https://www.adaptabletools.com/docs/reference/layoutextension.md#styledcolumn) | `string[]` | Names of Styled Columns which apply in this Layout |

### Base Layout Object 

| Property | Type | Description |
| --- | --- | --- |
| [AutoSizeColumns](https://www.adaptabletools.com/docs/reference/layoutbase.md#autosizecolumns) | `boolean` | Whether Columns should autosize when Layout first loads |
| [ColumnFilters](https://www.adaptabletools.com/docs/reference/layoutbase.md#columnfilters) | [`ColumnFilter`](https://www.adaptabletools.com/docs/reference/columnfilter.md)`[]` | Collection of Column Filters to apply in Layout |
| [ColumnGroupValues](https://www.adaptabletools.com/docs/reference/layoutbase.md#columngroupvalues) | [`ColumnGroupValues`](https://www.adaptabletools.com/docs/reference/columngroupvalues.md) | Defines which Column Groups are expanded / collapsed |
| [ColumnHeaders](https://www.adaptabletools.com/docs/reference/layoutbase.md#columnheaders) | [`ColumnStringMap`](https://www.adaptabletools.com/docs/reference/columnstringmap.md) | Set of custom header names for some (or all) Columns |
| [ColumnPinning](https://www.adaptabletools.com/docs/reference/layoutbase.md#columnpinning) | [`ColumnDirectionMap`](https://www.adaptabletools.com/docs/reference/columndirectionmap.md) | Columns pinned to an edge. Each entry is a column id set to `'left'` or `'right'`. Columns absent from the map are not pinned. |
| [ColumnSizing](https://www.adaptabletools.com/docs/reference/layoutbase.md#columnsizing) | [`ColumnSizingMap`](https://www.adaptabletools.com/docs/reference/columnsizingmap.md) | Controls size (width or flex & min/max) for Columns |
| [ColumnSorts](https://www.adaptabletools.com/docs/reference/layoutbase.md#columnsorts) | [`ColumnSort`](https://www.adaptabletools.com/docs/reference/columnsort.md)`[]` | Sorting to apply in the Layout |
| [GrandTotalRow](https://www.adaptabletools.com/docs/reference/layoutbase.md#grandtotalrow) | `'top' \| 'bottom' \| 'pinnedTop' \| 'pinnedBottom' \| boolean` | Where the grand total row is shown.<br/><br/>`'top'`, `'bottom'`, `'pinnedTop'` or `'pinnedBottom'`. `true` is the same as `'top'`. `false`, or omitting the property, turns the grand total row off. |
| [GridFilter](https://www.adaptabletools.com/docs/reference/layoutbase.md#gridfilter) | [`GridFilter`](https://www.adaptabletools.com/docs/reference/gridfilter.md) | Grid Filter to apply in Layout |
| [Name](https://www.adaptabletools.com/docs/reference/layoutbase.md#name) | `string` | Name of the Layout as it appears in the Layout toolbar and tool panel |
| [OpenCharts](https://www.adaptabletools.com/docs/reference/layoutbase.md#opencharts) | [`LayoutOpenChart`](https://www.adaptabletools.com/docs/reference/layoutopenchart.md)`[]` | AG Grid charts to open when this layout is selected (by chart UUID or name) |
| [RowGroupDisplayType](https://www.adaptabletools.com/docs/reference/layoutbase.md#rowgroupdisplaytype) | `RowGroupDisplayType` | How Row Groups are displayed: &#39;single&#39; - one hierarchical group Column; &#39;multi&#39; - a separate group Column per Row Grouped Column; &#39;groupRows&#39; - full-width group rows (no group column); defaults to &#39;single&#39; |
| [RowGroupValues](https://www.adaptabletools.com/docs/reference/layoutbase.md#rowgroupvalues) | [`RowGroupValues`](https://www.adaptabletools.com/docs/reference/rowgroupvalues.md) | Defines which Row Groups are expanded / collapsed |
| [RowSelection](https://www.adaptabletools.com/docs/reference/layoutbase.md#rowselection) | [`LayoutRowSelection`](https://www.adaptabletools.com/docs/reference/layoutrowselection.md)` \| false` | Defines Row Selection behaviour for Layout; if false, Row Selection is disabled; if undefined, GridOptions is used |
| [SuppressAggFuncInHeader](https://www.adaptabletools.com/docs/reference/layoutbase.md#suppressaggfuncinheader) | `boolean` | Hides the aggFunc in Column header: e.g. &#39;sum(Price)&#39; becomes &#39;Price&#39; |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/layoutbase.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |

### Table Layout Object 

| Property | Type | Description |
| --- | --- | --- |
| [ColumnVisibility](https://www.adaptabletools.com/docs/reference/tablelayout.md#columnvisibility) | [`ColumnBooleanFalseMap`](https://www.adaptabletools.com/docs/reference/columnbooleanfalsemap.md) | Columns to hide. Each entry is a column id set to `false`. Columns absent from the map stay visible. |
| [RowGroupedColumns](https://www.adaptabletools.com/docs/reference/tablelayout.md#rowgroupedcolumns) | `string[]` | Columns which are row-grouped when the Layout is applied |
| [RowSummaries](https://www.adaptabletools.com/docs/reference/tablelayout.md#rowsummaries) | [`RowSummary`](https://www.adaptabletools.com/docs/reference/rowsummary.md)`[]` | Pinned Rows that display Aggregation Info for a whole Column |
| [TableAggregationColumns](https://www.adaptabletools.com/docs/reference/tablelayout.md#tableaggregationcolumns) | [`TableAggregationColumns`](https://www.adaptabletools.com/docs/reference/tableaggregationcolumns.md) | Columns showing aggregated values in Grouped Rows; a record of ColumnId and aggfunc (e.g. sum) or &#39;true&#39; (to use default aggfunc) |
| [TableColumns](https://www.adaptabletools.com/docs/reference/tablelayout.md#tablecolumns) | `string[]` | Column ids in this layout, in display order. Required. |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/tablelayout.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |

#### Column Visibility

`ColumnVisibility` is a [`ColumnBooleanFalseMap`](https://www.adaptabletools.com/docs/reference/columnbooleanfalsemap.md). A column id set to `false` is hidden. Pivot Layouts do not have this property.

#### Row Summary

Each entry in `RowSummaries` is a [`RowSummary`](https://www.adaptabletools.com/docs/reference/rowsummary.md):

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [ColumnsMap](https://www.adaptabletools.com/docs/reference/rowsummary.md#columnsmap) | `Record<string, SummarySupportedExpression>` | Column id to summary name. Each value is a , for example `'SUM'` or `'AVG'`. |   |
| [IncludeOnlyFilteredRows](https://www.adaptabletools.com/docs/reference/rowsummary.md#includeonlyfilteredrows) | `boolean` | Evaluates only currently filtered rows in the summary | true |
| [Position](https://www.adaptabletools.com/docs/reference/rowsummary.md#position) | [`RowSummaryPosition`](https://www.adaptabletools.com/docs/reference/rowsummaryposition.md) | `'Top'` pins the summary above the rows. `'Bottom'` pins it below them. When omitted, the summary is pinned to the bottom. |   |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/rowsummary.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |   |
| [IsSuspended](https://www.adaptabletools.com/docs/reference/rowsummary.md#issuspended) | `boolean` | Suspends (i.e. turns off) an Adaptable Object |   |

`Position` is a [`RowSummaryPosition`](https://www.adaptabletools.com/docs/reference/rowsummaryposition.md):

[See API: rowsummaryposition](https://www.adaptabletools.com/docs/reference/rowsummaryposition.md)

#### Table Aggregation Columns

`TableAggregationColumns` is a list of aggregated columns:

```ts
{ ColumnId: string; AggFunc: AggregationColumnValue }[]
```

`AggFunc` is an AG Grid aggregation function name, `true` to use the column's default, or a [`WeightedAverageAggregation`](https://www.adaptabletools.com/docs/reference/weightedaverageaggregation.md):

| Property | Type | Description |
| --- | --- | --- |
| [type](https://www.adaptabletools.com/docs/reference/weightedaverageaggregation.md#type) | `'weightedAverage'` | Always `'weightedAverage'`. |
| [weightedColumnId](https://www.adaptabletools.com/docs/reference/weightedaverageaggregation.md#weightedcolumnid) | `string` | Column id whose values weight this average. That column is numeric. |

### Pivot Layout Object 

| Property | Type | Description |
| --- | --- | --- |
| [PivotAggregationColumns](https://www.adaptabletools.com/docs/reference/pivotlayout.md#pivotaggregationcolumns) | [`PivotAggregationColumns`](https://www.adaptabletools.com/docs/reference/pivotaggregationcolumns.md) | Columns showing aggregated values in Group Rows; 1st value in record is Column name, 2nd is either aggfunc (e.g. sum, avg etc.) or &#39;true&#39; (to use default aggfunc) |
| [PivotColumns](https://www.adaptabletools.com/docs/reference/pivotlayout.md#pivotcolumns) | `string[]` | Mandatory list of Columns to pivot (provide empty array if just displaying Aggregations) |
| [PivotColumnTotal](https://www.adaptabletools.com/docs/reference/pivotlayout.md#pivotcolumntotal) | [`PivotTotalPosition`](https://www.adaptabletools.com/docs/reference/pivottotalposition.md) | Display automatically calculated Totals within EACH Pivot Column Group, in the position specified |
| [PivotExpandLevel](https://www.adaptabletools.com/docs/reference/pivotlayout.md#pivotexpandlevel) | `number` | How deep to expand Pivot Columns (0 for none, 1 for 1st level only etc, -1 to expand all) |
| [PivotGrandTotal](https://www.adaptabletools.com/docs/reference/pivotlayout.md#pivotgrandtotal) | [`PivotTotalPosition`](https://www.adaptabletools.com/docs/reference/pivottotalposition.md) | Display automatically calculated Totals of all Pivot Columns, in the position specified |
| [PivotGroupedColumns](https://www.adaptabletools.com/docs/reference/pivotlayout.md#pivotgroupedcolumns) | `string[]` | Columns which are row-grouped when the Layout is applied |
| [PivotResultColumnsOrder](https://www.adaptabletools.com/docs/reference/pivotlayout.md#pivotresultcolumnsorder) | `string[] \| boolean` | Ordered list of Pivot Result Columns; set to `true` to track current display order, or provide custom list |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/pivotlayout.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |

#### Pivot Aggregation Columns

`PivotAggregationColumns` is a list of aggregated columns:

```ts
{
  ColumnId: string;
  AggFunc: AggregationColumnValue;
  Total?: PivotTotalPosition | { PivotColumnId: string; ShowTotal?: PivotTotalPosition }[];
}[]
```

`AggFunc` is an AG Grid aggregation function name, `true` to use the column's default, or a [`WeightedAverageAggregation`](https://www.adaptabletools.com/docs/reference/weightedaverageaggregation.md):

| Property | Type | Description |
| --- | --- | --- |
| [type](https://www.adaptabletools.com/docs/reference/weightedaverageaggregation.md#type) | `'weightedAverage'` | Always `'weightedAverage'`. |
| [weightedColumnId](https://www.adaptabletools.com/docs/reference/weightedaverageaggregation.md#weightedcolumnid) | `string` | Column id whose values weight this average. That column is numeric. |

`PivotTotalPosition` is:

[See API: pivottotalposition](https://www.adaptabletools.com/docs/reference/pivottotalposition.md)

## Both Layouts

These properties are on [`LayoutBase`](https://www.adaptabletools.com/docs/reference/layoutbase.md), so a Table Layout and a Pivot Layout both have them.

### Column Filter

The `ColumnFilters` property is a collection of [`ColumnFilter`](https://www.adaptabletools.com/docs/reference/columnfilter.md) objects defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [ColumnId](https://www.adaptabletools.com/docs/reference/columnfilter.md#columnid) | `string` | Column where Filter should be applied |
| [Expression](https://www.adaptabletools.com/docs/reference/columnfilter.md#expression) | `string` | AdaptableQL boolean expression evaluated for each row, e.g.<br/><br/>`[price] > 100 AND [price] < 200 OR [price] = 350`<br/><br/>Mutually exclusive with : when<br/>`Expression` is set, `PreferredFilter` is not persisted. |
| [PreferredFilter](https://www.adaptabletools.com/docs/reference/columnfilter.md#preferredfilter) | `string` | Preferred filter operator when there is no `Expression` (UI seed only —<br/>does not filter rows). Uses AQL operator / function names, the same<br/>vocabulary as `columnFilterOptions.default*ColumnFilter` (e.g. `'IN'`,<br/>`'STARTS_WITH'`, `'EQ'`).<br/><br/>Mutually exclusive with : set when the<br/>user selects an operator before the filter is complete; removed as<br/>soon as a valid `Expression` is persisted; restored from the current<br/>UI operator when the `Expression` is cleared. |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/columnfilter.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |
| [IsSuspended](https://www.adaptabletools.com/docs/reference/columnfilter.md#issuspended) | `boolean` | Suspends (i.e. turns off) an Adaptable Object |

### Grid Filter

The [`GridFilter`](https://www.adaptabletools.com/docs/reference/gridfilter.md) object is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [Expression](https://www.adaptabletools.com/docs/reference/gridfilter.md#expression) | `string` | The (boolean) Expression to run |
| [IsReadOnly](https://www.adaptabletools.com/docs/reference/gridfilter.md#isreadonly) | `boolean` | Sets Entity to ReadOnly (overwriting a Strategy Entitlement of &#39;Full&#39;) |
| [IsSuspended](https://www.adaptabletools.com/docs/reference/gridfilter.md#issuspended) | `boolean` | Suspends (i.e. turns off) an Adaptable Object |

### Column Sort

The [`ColumnSort`](https://www.adaptabletools.com/docs/reference/columnsort.md) object used for sorting is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [ColumnId](https://www.adaptabletools.com/docs/reference/columnsort.md#columnid) | `string` | Id of Column being sorted |
| [SortOrder](https://www.adaptabletools.com/docs/reference/columnsort.md#sortorder) | `'Asc' \| 'Desc'` | How Column is sorted - either &#39;Asc&#39; or &#39;Desc&#39; |

### Row Selection

The [`LayoutRowSelection`](https://www.adaptabletools.com/docs/reference/layoutrowselection.md) object used for row selection is defined as follows:

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [Checkboxes](https://www.adaptabletools.com/docs/reference/layoutrowselection.md#checkboxes) | `boolean` | Whether to display checkboxes in Selection Column.<br/>Overridden by `LayoutOptions.isRowSelectionCheckboxVisible` when that function is provided<br/>(except when `RowSelection` is `false`, which disables selection entirely). | true |
| [CheckboxInGroupColumn](https://www.adaptabletools.com/docs/reference/layoutrowselection.md#checkboxingroupcolumn) | `boolean` | Renders selection checkboxes in Auto-Group Column (if `true`) or in dedicated Selection Column (if `false`) | false |
| [EnableClickSelection](https://www.adaptabletools.com/docs/reference/layoutrowselection.md#enableclickselection) | `boolean \| 'enableDeselection' \| 'enableSelection'` | Selection behaviour when clicking a row: &#39;enableSelection&#39; \| &#39;enableDeselection&#39; \| true \| false | false |
| [GroupSelectMode](https://www.adaptabletools.com/docs/reference/layoutrowselection.md#groupselectmode) | `GroupSelectionMode` | Grouping Select Mode: &#39;self&#39; \| &#39;descendants&#39; \| &#39;filteredDescendants&#39; | &#39;self&#39; |
| [HeaderCheckbox](https://www.adaptabletools.com/docs/reference/layoutrowselection.md#headercheckbox) | `boolean` | Whether to show checkbox in Header of Selection Column Header (&#39;multiRow&#39; only) | true |
| [Mode](https://www.adaptabletools.com/docs/reference/layoutrowselection.md#mode) | `'singleRow' \| 'multiRow'` | Row Selection Mode: &#39;singleRow&#39; or &#39;multiRow&#39; |   |
| [SelectAllMode](https://www.adaptabletools.com/docs/reference/layoutrowselection.md#selectallmode) | `SelectAllMode` | Select All Mode: &#39;all&#39; \| &#39;filtered&#39; \| &#39;currentPage&#39; | &#39;all&#39; |

### Column Pinning

`ColumnPinning` is a [`ColumnDirectionMap`](https://www.adaptabletools.com/docs/reference/columndirectionmap.md). Each column id is `'left'` or `'right'`.

### Column Sizing

`ColumnSizing` is a [`ColumnSizingMap`](https://www.adaptabletools.com/docs/reference/columnsizingmap.md) of [`ColumnSizingDefinition`](https://www.adaptabletools.com/docs/reference/columnsizingdefinition.md) values. Set `Width` or `Flex`, not both.

| Property | Type | Description |
| --- | --- | --- |
| `Width` | `number` | Column width in pixels |
| `Flex` | `number` | Flex grow |
| `Resizable` | `boolean` | Whether the column can be resized |
| `MinWidth` | `number` | Minimum width |
| `MaxWidth` | `number` | Maximum width |

### Column Headers

`ColumnHeaders` is a [`ColumnStringMap`](https://www.adaptabletools.com/docs/reference/columnstringmap.md). Each column id maps to its header text.

### Row Group Values

`RowGroupValues` is either `{ RowGroupDefaultBehavior: 'always-expanded' | 'always-collapsed' }`, or a [`RowGroupValuesWithExceptionKeys`](https://www.adaptabletools.com/docs/reference/rowgroupvalueswithexceptionkeys.md): `{ RowGroupDefaultBehavior: 'expanded' | 'collapsed' }` together with `ExceptionGroupKeys` or `GroupKeys`.

[`GroupKeys`](https://www.adaptabletools.com/docs/reference/groupkeys.md) is defined as follows:

| Property | Type | Description |
| --- | --- | --- |
| [ExceptionGroupKeys](https://www.adaptabletools.com/docs/reference/groupkeys.md#exceptiongroupkeys) | `any[][]` | Group-key paths that do the opposite of `RowGroupDefaultBehavior`. Each inner array is one path from the top group down. |
| [RowGroupedColumns](https://www.adaptabletools.com/docs/reference/groupkeys.md#rowgroupedcolumns) | `string[]` | Row-grouped column ids this exception list applies to. Matched against the layout&#39;s current row-grouped columns. |

### Column Group Values

`ColumnGroupValues` is either `{ ColumnGroupDefaultBehavior: 'always-expanded' | 'always-collapsed' }`, or a [`ColumnGroupValuesWithExceptionKeys`](https://www.adaptabletools.com/docs/reference/columngroupvalueswithexceptionkeys.md):

```ts
{
  ColumnGroupDefaultBehavior: 'expanded' | 'collapsed';
  ExceptionGroupKeys?: any[];
}
```

### Open Charts

`OpenCharts` is a list of [`LayoutOpenChart`](https://www.adaptabletools.com/docs/reference/layoutopenchart.md) objects:

| Property | Type | Description |
| --- | --- | --- |
| [ChartName](https://www.adaptabletools.com/docs/reference/layoutopenchart.md#chartname) | `string` | Name of a persisted chart in `Charting.ChartDefinitions` (must be unique among all charts) |
| [ContainerName](https://www.adaptabletools.com/docs/reference/layoutopenchart.md#containername) | `string` | Optional `chartContainers` name, or omit for the AG Grid chart window |

-------------

## Layout Options

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [autoCreateLayout](https://www.adaptabletools.com/docs/reference/layoutoptions.md#autocreatelayout) | `boolean \| `[`AutoCreateLayoutOptions`](https://www.adaptabletools.com/docs/reference/autocreatelayoutoptions.md) | Creates a Default Layout based on AG Grid ColDefs, with optons to add a name and set if created on every load | undefined |
| [autoRemoveDeletedColumnsFromLayouts](https://www.adaptabletools.com/docs/reference/layoutoptions.md#autoremovedeletedcolumnsfromlayouts) | `boolean` | When a Calculated or Free Text Column is deleted, also remove it from all Layouts and layout properties | true |
| [enableLayoutExtensionsUI](https://www.adaptabletools.com/docs/reference/layoutoptions.md#enablelayoutextensionsui) | `boolean` | Show controls for extending objects (e.g. Alerts, Format Columns) into Layouts - a Layouts step in wizards and Add/Remove buttons in Settings Panel | false |
| [isRowSelectionCheckboxVisible](https://www.adaptabletools.com/docs/reference/layoutoptions.md#isrowselectioncheckboxvisible) | `(context: `[`LayoutRowSelectionContext`](https://www.adaptabletools.com/docs/reference/layoutrowselectioncontext.md)`<TData>) => boolean` | Sets if Row Selection checkbox should be visible for a given row |   |
| [layoutCreationDefaultProperties](https://www.adaptabletools.com/docs/reference/layoutoptions.md#layoutcreationdefaultproperties) | [`LayoutCreationDefaultProperties`](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultproperties.md)` \| ((context: `[`LayoutCreationDefaultPropertiesContext`](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultpropertiescontext.md)`) => `[`TableLayoutCreationDefaultProperties`](https://www.adaptabletools.com/docs/reference/tablelayoutcreationdefaultproperties.md)` \| `[`PivotLayoutCreationDefaultProperties`](https://www.adaptabletools.com/docs/reference/pivotlayoutcreationdefaultproperties.md)`)` | Default properties to apply when creating a new Layout (Table or Pivot) |   |
| [layoutViewOptions](https://www.adaptabletools.com/docs/reference/layoutoptions.md#layoutviewoptions) | [`LayoutViewOptions`](https://www.adaptabletools.com/docs/reference/layoutviewoptions.md) | Set of options for how Layouts are displayed in Settings Panel |   |
| [pivotPreviewColumns](https://www.adaptabletools.com/docs/reference/layoutoptions.md#pivotpreviewcolumns) | `string[] \| ((context: `[`PivotPreviewColumnsContext`](https://www.adaptabletools.com/docs/reference/pivotpreviewcolumnscontext.md)`) => string[])` | Columns to display in Table that opens when viewing Pivot Cell contents |   |

- Use `LayoutExtensions` in Layout State (and `enableLayoutExtensionsUI` in Layout Options) to scope objects to Layouts. Object Tags do not control Layout membership.
- `autoCreateLayout` builds a first-run Layout from AG Grid ColDefs when no Layouts exist. `{ createEveryLoad: true }` rebuilds that Layout from ColDefs on every load. See [Default Layouts](https://www.adaptabletools.com/docs/handbook-layouts-default/index.md).

This includes `isRowSelectionCheckboxVisible` for per-row Selection checkbox visibility — see [Checkbox Visibility](https://www.adaptabletools.com/docs/handbook-layouts-table-row-selection/index.md#checkbox-visibility).

### Layout View Options

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [maxColumnsToDisplay](https://www.adaptabletools.com/docs/reference/layoutviewoptions.md#maxcolumnstodisplay) | `number` | How many Column Names to display in inline Layout preview | 10 |

### Auto Create Layout

`autoCreateLayout` may be a boolean or an [`AutoCreateLayoutOptions`](https://www.adaptabletools.com/docs/reference/autocreatelayoutoptions.md) object:

| Property | Type | Description | Default |
| --- | --- | --- | --- |
| [createEveryLoad](https://www.adaptabletools.com/docs/reference/autocreatelayoutoptions.md#createeveryload) | `boolean` | Rebuild Layout from ColDefs on every load (edits persist but next load replaces them) | false |
| [name](https://www.adaptabletools.com/docs/reference/autocreatelayoutoptions.md#name) | `string` | Name of Layout to create | &#39;Default Layout&#39; |

### Default Properties

`layoutCreationDefaultProperties` is a [`LayoutCreationDefaultProperties`](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultproperties.md) object, or a function that receives [`LayoutCreationDefaultPropertiesContext`](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultpropertiescontext.md) and returns the table or pivot defaults:

| Property | Type | Description |
| --- | --- | --- |
| [pivotLayout](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultproperties.md#pivotlayout) | [`PivotLayoutCreationDefaultProperties`](https://www.adaptabletools.com/docs/reference/pivotlayoutcreationdefaultproperties.md) | Default properties to apply when creating a new Pivot Layout |
| [tableLayout](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultproperties.md#tablelayout) | [`TableLayoutCreationDefaultProperties`](https://www.adaptabletools.com/docs/reference/tablelayoutcreationdefaultproperties.md) | Default properties to apply when creating a new Table Layout |

`tableLayout` is `Partial<Omit<TableLayout, 'Name'>>`. `pivotLayout` is `Partial<Omit<PivotLayout, 'Name'>>`.

| Property | Type | Description |
| --- | --- | --- |
| [layoutType](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultpropertiescontext.md#layouttype) | `'table' \| 'pivot'` | Type of Layout (&#39;table&#39; \| &#39;pivot&#39;) |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/layoutcreationdefaultpropertiescontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

### Row selection checkbox

`isRowSelectionCheckboxVisible` receives a [`LayoutRowSelectionContext`](https://www.adaptabletools.com/docs/reference/layoutrowselectioncontext.md):

| Property | Type | Description |
| --- | --- | --- |
| [data](https://www.adaptabletools.com/docs/reference/layoutrowselectioncontext.md#data) | `TData \| undefined` | The data in the Row Node.<br/>`undefined` for group, footer, pinned, and other non-data rows — use `rowNode` for those cases. |
| [layout](https://www.adaptabletools.com/docs/reference/layoutrowselectioncontext.md#layout) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md) | Current Layout |
| [rowNode](https://www.adaptabletools.com/docs/reference/layoutrowselectioncontext.md#rownode) | `IRowNode<TData>` | The Row Node being evaluated |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/layoutrowselectioncontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

### Pivot preview columns

`pivotPreviewColumns` is a column-id list, or a function that receives [`PivotPreviewColumnsContext`](https://www.adaptabletools.com/docs/reference/pivotpreviewcolumnscontext.md):

| Property | Type | Description |
| --- | --- | --- |
| [columnId](https://www.adaptabletools.com/docs/reference/pivotpreviewcolumnscontext.md#columnid) | `string` | Column being opened |
| [layout](https://www.adaptabletools.com/docs/reference/pivotpreviewcolumnscontext.md#layout) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md) | Current Layout |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/pivotpreviewcolumnscontext.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

-------------

## Layout API

Full programmatic access to Layouts and related features is available in [`Layout API`](https://www.adaptabletools.com/docs/reference/layoutapi.md) section of [Adaptable API](https://www.adaptabletools.com/docs/technical-reference-adaptable-api/index.md) .

This enables Layouts to be accessed, created, edited, cloned, deleted and shared programmatically.

| Method | Returns | Description |
| --- | --- | --- |
| [addColumnToCurrentLayout(columnId)](https://www.adaptabletools.com/docs/reference/layoutapi.md#addcolumntocurrentlayout) | `void` | Adds a Column to Current Table or Pivot Layout |
| [addObjectToLayout(object, module, layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#addobjecttolayout) | `void` | Extends an object into a Layout - once extended into any Layout, it applies only in those Layouts |
| [cloneAndSetLayout(layoutToClone, layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#cloneandsetlayout) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md)` \| false` | Creates new Layout by cloning a given Layout and then loads it into Grid |
| [cloneExtendedLayout(extendedLayoutToClone, layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#cloneextendedlayout) | [`ExtendedLayout`](https://www.adaptabletools.com/docs/reference/extendedlayout.md)` \| false` | Clones an Extended Layout - the new Layout is extended with the same objects |
| [cloneLayout(layoutToClone, layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#clonelayout) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md)` \| false` | Creates new Layout by cloning a given Layout |
| [createAndSetLayout(layoutToCreate)](https://www.adaptabletools.com/docs/reference/layoutapi.md#createandsetlayout) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md)` \| false` | Creates new Layout and loads it into Grid |
| [createLayout(layoutToCreate)](https://www.adaptabletools.com/docs/reference/layoutapi.md#createlayout) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md)` \| false` | Creates a new Layout |
| [createOrUpdateExtendedLayout(extendedLayout)](https://www.adaptabletools.com/docs/reference/layoutapi.md#createorupdateextendedlayout) | `void` | Creates (or Updates) an Extended Layout: saves the Layout, adds any extension objects not yet in state,<br/>and makes those objects the Layout&#39;s complete Layout Extension |
| [createOrUpdateLayout(layout)](https://www.adaptabletools.com/docs/reference/layoutapi.md#createorupdatelayout) | `void` | Creates new Layout into Adaptable State or updates an existing Layout (with same name or id) |
| [deleteLayout(layout)](https://www.adaptabletools.com/docs/reference/layoutapi.md#deletelayout) | `void` | Deletes an existing Layout (if not Default or only existing Layout) |
| [deleteLayoutByName(layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#deletelayoutbyname) | `void` | Deletes a Layout by name. Does nothing when it is the only Layout. |
| [doesLayoutExist(layout)](https://www.adaptabletools.com/docs/reference/layoutapi.md#doeslayoutexist) | `boolean` | Whether this Layout is already in Layout State. Compared by `Uuid`. |
| [getCurrentLayout()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getcurrentlayout) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md) | Retrieves Current Layout from Layout State |
| [getCurrentLayoutColumnSort(columnId)](https://www.adaptabletools.com/docs/reference/layoutapi.md#getcurrentlayoutcolumnsort) | [`ColumnSort`](https://www.adaptabletools.com/docs/reference/columnsort.md)`['SortOrder'] \| null` | The sort direction of a column in the current Layout. |
| [getCurrentLayoutName()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getcurrentlayoutname) | `string` | Name of the Layout that is selected. |
| [getCurrentRowGroupsColumnIds()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getcurrentrowgroupscolumnids) | `string[]` | Columns that group rows in the current Layout. |
| [getCurrentVisibleColumnIdsForPivotLayout()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getcurrentvisiblecolumnidsforpivotlayout) | `string[]` | Column ids currently displayed in a Pivot Layout. |
| [getCurrentVisibleColumnIdsForTableLayout()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getcurrentvisiblecolumnidsfortablelayout) | `string[]` | Column ids currently displayed in a Table Layout. |
| [getCurrentVisibleColumnIdsMapForTableLayout()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getcurrentvisiblecolumnidsmapfortablelayout) | `\{ [key: string]: boolean; \}` | Column ids in the current Table Layout. |
| [getExtendedLayoutByName(layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#getextendedlayoutbyname) | [`ExtendedLayout`](https://www.adaptabletools.com/docs/reference/extendedlayout.md)` \| undefined` | Retrieves the Layout with the given name, together with the objects extended into it<br/>(global objects, which apply in every Layout, are not included) |
| [getLayoutById(id)](https://www.adaptabletools.com/docs/reference/layoutapi.md#getlayoutbyid) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md) | Retrieves Layout by by the technical ID (from `LayoutState`) |
| [getLayoutByName(layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#getlayoutbyname) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md)` \| null` | Retrieves Layout with the given name |
| [getLayoutExtensions(layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#getlayoutextensions) | [`LayoutExtensionInfo`](https://www.adaptabletools.com/docs/reference/layoutextensioninfo.md) | Retrieves the names of the objects, per Module, extended into a Layout |
| [getLayouts()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getlayouts) | [`Layout`](https://www.adaptabletools.com/docs/reference/layout.md)`[]` | Retrieves all Layouts in Adaptable State |
| [getLayoutsForObject(object, module)](https://www.adaptabletools.com/docs/reference/layoutapi.md#getlayoutsforobject) | `string[]` | Retrieves the names of the Layouts an object is extended into (empty when the object is global) |
| [getLayoutState()](https://www.adaptabletools.com/docs/reference/layoutapi.md#getlayoutstate) | [`LayoutState`](https://www.adaptabletools.com/docs/reference/layoutstate.md) | The Layout section of Adaptable State. |
| [isCurrentLayoutPivot()](https://www.adaptabletools.com/docs/reference/layoutapi.md#iscurrentlayoutpivot) | `boolean` | Whether the current Layout is a Pivot Layout. |
| [openLayoutSettingsPanel()](https://www.adaptabletools.com/docs/reference/layoutapi.md#openlayoutsettingspanel) | `void` | Opens Settings Panel with Layout section selected |
| [removeColumnFromCurrentLayout(columnId)](https://www.adaptabletools.com/docs/reference/layoutapi.md#removecolumnfromcurrentlayout) | `void` | Removes a Column from Current Table or Pivot Layout |
| [removeObjectFromLayout(object, module, layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#removeobjectfromlayout) | `void` | Removes an object from a Layout - when it is no longer extended into any Layout, it becomes global |
| [renameLayout(layoutName, newLayoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#renamelayout) | `boolean` | Renames a Layout, keeping the objects extended into it |
| [saveCurrentLayout()](https://www.adaptabletools.com/docs/reference/layoutapi.md#savecurrentlayout) | `void` | Saves current Layout - using column order, visibility, sorting etc. currently in use in the grid |
| [setColumnCaption(columnId, caption)](https://www.adaptabletools.com/docs/reference/layoutapi.md#setcolumncaption) | `void` | Sets a new Caption / Header for a Column (only for current Layout) |
| [setExtendedLayout(extendedLayout)](https://www.adaptabletools.com/docs/reference/layoutapi.md#setextendedlayout) | `void` | Sets (i.e. selects) the Extended Layout |
| [setLayout(layoutName)](https://www.adaptabletools.com/docs/reference/layoutapi.md#setlayout) | `void` | Sets (i.e. selects) the Layout |
| [setLayoutExtensions(layoutName, extensionInfo)](https://www.adaptabletools.com/docs/reference/layoutapi.md#setlayoutextensions) | `void` | Replaces the objects extended into a Layout (an empty extensionInfo makes those objects global again, unless<br/>they are extended into other Layouts) |
| [setLayoutsForObject(object, module, layoutNames)](https://www.adaptabletools.com/docs/reference/layoutapi.md#setlayoutsforobject) | `void` | Extends an object into exactly the given Layouts, removing it from any others |
| [showChangeColumnCaption(column)](https://www.adaptabletools.com/docs/reference/layoutapi.md#showchangecolumncaption) | `void` | Opens Change Column Caption popup |
| [showLayoutEditor(layoutName, layoutType, action)](https://www.adaptabletools.com/docs/reference/layoutapi.md#showlayouteditor) | `void` | Opens Layout Editor - for Current or a named Layout |
| [updateCurrentLayout(updateFn)](https://www.adaptabletools.com/docs/reference/layoutapi.md#updatecurrentlayout) | `void` | Updates current Layout using the partial Layout props provided in a function |

-------------

## Layout Changed Event

The Layout Changed Event fires whenever Layout State changes.

The Event Info is a single [`LayoutChangedInfo`](https://www.adaptabletools.com/docs/reference/layoutchangedinfo.md) object. It includes the previous and current Layout State, plus:

- `actionName` — why the Event fired
- `changedAreas` — which parts of the current Layout changed, when the Layout is edited in place

### Layout Changed Info

| Property | Type | Description |
| --- | --- | --- |
| [actionName](https://www.adaptabletools.com/docs/reference/layoutchangedinfo.md#actionname) | [`LayoutChangedAction`](https://www.adaptabletools.com/docs/reference/layoutchangedaction.md) | Which action caused this change. See . |
| [changedAreas](https://www.adaptabletools.com/docs/reference/layoutchangedinfo.md#changedareas) | [`LayoutChangedArea`](https://www.adaptabletools.com/docs/reference/layoutchangedarea.md)`[]` | Which parts of the **current** Layout changed.<br/><br/>Use this when you care *what* changed, rather than which `actionName` fired:<br/><br/>- `LAYOUT_SAVE`: diffs non-filter facets (e.g. `ColumnSorting`, `RowGrouping`)<br/>- Column Filter actions: always `['ColumnFilter']`<br/>- Grid Filter actions: always `['GridFilter']`<br/><br/>Omitted for layout identity changes (`LAYOUT_SELECT`, `LAYOUT_ADD`, `LAYOUT_DELETE`, `LAYOUT_READY`). |
| [newLayoutState](https://www.adaptabletools.com/docs/reference/layoutchangedinfo.md#newlayoutstate) | [`LayoutState`](https://www.adaptabletools.com/docs/reference/layoutstate.md) | Layout State after this change. |
| [oldLayoutState](https://www.adaptabletools.com/docs/reference/layoutchangedinfo.md#oldlayoutstate) | [`LayoutState`](https://www.adaptabletools.com/docs/reference/layoutstate.md)` \| undefined` | Layout State before this change.<br/><br/>Absent for `LAYOUT_READY`, which fires once after startup and has no previous state. |
| [adaptableContext](https://www.adaptabletools.com/docs/reference/layoutchangedinfo.md#adaptablecontext) | `any` | Custom application Context provided in `AdaptableOptions.adaptableContext` |

### Event Subscription

Subscribing to the Event is done the same way as with all [Adaptable Events](https://www.adaptabletools.com/docs/technical-reference-adaptable-events/index.md):

```ts
api.eventApi.on('LayoutChanged', (eventInfo: LayoutChangedInfo) => {
    // do something with the info
});
```

### Layout Actions

Every Layout Changed Event includes an Action, which describes what caused the Layout to change.

This is provided using the `actionName` property which is of type [`LayoutChangedAction`](https://www.adaptabletools.com/docs/reference/layoutchangedaction.md).

| Action                                                | Description                                                                                        |
| ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
| `LAYOUT_READY`                       | Fired once after AdapTable starts, for the Layout that is already current                          |
| `LAYOUT_ADD`                         | A Layout has been added                                                                            |
| `LAYOUT_EDIT`                        | A Layout has been edited                                                                           |
| `LAYOUT_SAVE`                        | A Layout has been saved, including auto-save after grid edits (sort, grouping, columns, and so on) |
| `LAYOUT_DELETE`                      | A Layout has been deleted                                                                          |
| `LAYOUT_SELECT`                      | A different Layout has been selected                                                               |
| `LAYOUT_COLUMN_FILTER_ADD`           | A Column Filter has been added                                                                     |
| `LAYOUT_COLUMN_FILTER_EDIT`          | A Column Filter has been edited                                                                    |
| `LAYOUT_COLUMN_FILTER_SET`           | Column Filters have been set                                                                       |
| `LAYOUT_COLUMN_FILTER_CLEAR`         | A Column Filter has been cleared                                                                   |
| `LAYOUT_COLUMN_FILTER_CLEAR_ALL`     | All Column Filters have been cleared                                                               |
| `LAYOUT_COLUMN_FILTER_SUSPEND`       | A Column Filter has been suspended                                                                 |
| `LAYOUT_COLUMN_FILTER_SUSPEND_ALL`   | All Column Filters have been suspended                                                             |
| `LAYOUT_COLUMN_FILTER_UNSUSPEND`     | A Column Filter has been unsuspended                                                               |
| `LAYOUT_COLUMN_FILTER_UNSUSPEND_ALL` | All Column Filters have been unsuspended                                                           |
| `LAYOUT_GRID_FILTER_SET`             | The Grid Filter has been set                                                                       |
| `LAYOUT_GRID_FILTER_CLEAR`           | The Grid Filter has been cleared                                                                   |
| `LAYOUT_GRID_FILTER_SUSPEND`         | The Grid Filter has been suspended                                                                 |
| `LAYOUT_GRID_FILTER_UNSUSPEND`       | The Grid Filter has been unsuspended                                                               |

### Layout Changed Areas

`changedAreas` is for when you care which part of the current Layout changed, without enumerating every filter `actionName` or deep-diffing Layout State.

It is only set when the current Layout is edited in place:

- `LAYOUT_SAVE` — AdapTable diffs the previous and next Layout and lists the facets that actually changed (sort, grouping, columns, and so on)
- any Column Filter action — always `['ColumnFilter']`
- any Grid Filter action — always `['GridFilter']`

- It is omitted for Layout identity changes: `LAYOUT_SELECT`, `LAYOUT_ADD`, `LAYOUT_DELETE` and `LAYOUT_READY`
- Those change which Layout is current (or that a Layout exists), not a facet of the current one

Column sizing is not included because AG Grid often reports incidental width or flex changes on unrelated edits

The possible values are of type [`LayoutChangedArea`](https://www.adaptabletools.com/docs/reference/layoutchangedarea.md):

| Area            | Description                                              |
| --------------- | -------------------------------------------------------- |
| `Columns`       | Visible columns or column order changed                  |
| `ColumnPinning` | Column pinning changed                                   |
| `ColumnHeaders` | Column captions (or suppress agg func in header) changed |
| `ColumnSorting` | Column sorts changed                                     |
| `RowGrouping`   | Row grouping (table or pivot) changed                    |
| `Aggregations`  | Table or pivot aggregations changed                      |
| `RowSummaries`  | Row summaries changed                                    |
| `RowSelection`  | Layout row-selection settings changed                    |
| `ColumnFilter`  | A Column Filter action fired                             |
| `GridFilter`    | A Grid Filter action fired                               |
| `Pivoting`      | Pivot columns, expand level or pivot totals changed      |

See [Monitoring Layout Changes](https://www.adaptabletools.com/docs/handbook-layouts-monitoring/index.md) for a worked example