Apex Grid Column Configuration

The columns are defined with the columns property which has the type ColumnConfiguration[].key is the only required property for the ColumnConfiguration as the column identifier. It is also the property that is used to map and render the relevant data in the grid rows.

const accountColumn: ColumnConfiguration = {
  key: 'account',

  /* Additional configuration follows */
  ...
};

As a rule of thumb, the column prop should keep the same reference between renders. The columns are designed to be definitions and rarely change once the grid is mounted unless explicitly requested. Otherwise, you take the risk of losing state such as width, renderers, etc., and additional render cycles which may lead to performance degradation.

Depending on the technology stack which you use, you can create the array outside the appropriate render function/mechanism or memoize it.

Configuration based on the data source

The grid supports inferring the column configuration based on the provided data source. It tries to infer the appropriate key and type props based on records in the data.

const data: Record[] = [
  { entryId: "1234", source: "https://example.com", ts: 1373521917579 },
  ...
];

<apex-grid auto-generate .data=${data}></apex-grid>

The previous snippet will result in the following column configuration for the grid:

[
  { key: 'entryId', type: 'string' },
  { key: 'source', type: 'string' },
  { key: 'ts', type: 'number' },
];

Useful for a quick render of some data without any additional customizations.

This is a one-time operation that is executed when the grid is initially added to the DOM. Passing an empty data source or having a late bound data source (such as an HTTP request) will usually result in an empty column configuration for the grid.

This property is ignored if any existing column configuration already exists in the grid. See the data binding topic for additional information on auto-generating the column configuration based on the data source.

Additional column configuration

The column configuration object exposes several more properties:

Column width

By default, the columns have a width of minmax(136px, 1fr) which translates to a minimum width of 136px and a maximum of 1 part of the available space in the Apex grid. This way the columns are fluid and responsive accommodating for changes in the grid width.

To change the width of column, use the width property of the ColumnConfiguration object.

{
  ...
  width: '250px'
}

The property accepts valid CSS length units.

Hiding columns

Columns can be hidden/shown by setting the hidden property to the column configuration object.

{
  ...,
  hidden: true
}

Column resize

Each column of the Apex grid can be configured to be resizable by setting the resizable property in the column definition.

{
  ...
  resizable: true
}

If a column is set to be resizable, you can drag the right side of the column header to either increase/decrease the column width. Double-clicking on the resize area will trigger auto-sizing of the column where it will try to set its width according to the largest content of its cells/header.

Columns with "fluid" widths (fr, %, etc.) can behave erratically when resizing in the grid is performed as they try to accommodate the new dimensions. Depending on the application scenario, it may be better to use "hard" units so users don't experience layout shifts.

In the sample below you can try out the different column properties and how they reflect in the rendered grid.

Header extras

Since v3.3 the header row carries a few discoverability features that sit alongside the sort and filter affordances.

Every column header shows an always-visible column-menu (three-dot / kebab) button. Out of the box it offers Sort Ascending, Sort Descending, and Autosize Column (on sortable or resizable columns). A feature module can fill the menu instead through the ColumnMenuProvider seam: apex-grid-enterprise populates it with pin, hide, group, and chart actions, shared with the right-click context menu.

grid.columnMenu = true;    // default
grid.columnMenu = false;   // hide the kebab button entirely

Hiding it with columnMenu = false removes the button; a module's menu stays reachable by right-click.

Column separators

A persistent vertical divider renders on each column header's trailing edge, on by default. On columns that opt into resizing (resizable: true) the divider doubles as the resize grab target.

grid.columnSeparator = false;    // hide the dividers

Because the default is true, disable it through the property (a default-on boolean attribute cannot be turned off by markup alone). Theme the line with --ag-header-separator and set its vertical inset with --apex-header-separator-inset; see Styles & Themes.

Spreadsheet coordinates

Set coordinateHints to reveal a leading row-number gutter (1, 2, 3, …) and A / B / C column-letter chips in the headers, so cell references are discoverable (a spreadsheet-style look):

grid.coordinateHints = true;

<apex-grid coordinate-hints></apex-grid>

apex-grid-enterprise turns this on automatically for any grid that has an allowFormula column (see the Formula Engine), so the gutter is reserved up front and entering a formula never shifts the layout.