Column

This config enables automatic height for all cells in this column. It is achieved by measuring the height a cell after rendering it to DOM, and then sizing the row using that height (if it is greater than other heights used for the row).

Heads up if you render your Grid on page load, if measurement happens before the font you are using is loaded you might get slightly incorrect heights. For browsers that support it we detect that and remeasure when fonts are available.

NOTE: Enabling this config comes with a pretty big performance hit. To maintain good performance, we recommend not using it. You can still set the height of individual rows manually, either through data or via renderers.

Also note that this setting only works fully as intended with non-flex columns.

Rows will always be at least rowHeight pixels tall even if an autoHeight cell contains no data.

Manually setting a height from a renderer in this column will take precedence over this config.

Has a corresponding autoHeight config.

This config sizes a column to fits its content. It is used instead of width or flex.

This config requires the ColumnAutoWidth feature which responds to changes in the grid's store and synchronizes the widths' of all autoWidth columns.

If this config is not a Boolean value, it is passed as the only argument to the resizeToFitContent method to constrain the column's width.

Has a corresponding autoWidth config.

The name of the data model field to read a cells value from.

Also accepts dot notation to read nested or related data, for example 'address.city'.

Has a corresponding field config.

The child element into which content should be placed. This means where any contained widgets such as filter input fields should be rendered. Only available after the grid has been rendered.

Note that column headers are rerendered upon mutation of Column values, so this value is volatile and should not be cached, but should be read whenever needed.

The header element for this Column. Only available after the grid has been rendered.

Note that column headers are rerendered upon mutation of Column values, so this value is volatile and should not be cached, but should be read whenever needed.

The text containing element for this Column. Only available after the grid has been rendered.

Note that column headers are rerendered upon mutation of Column values, so this value is volatile and should not be cached, but should be read whenever needed.

The text wrapping element for this Column. Only available after the grid has been rendered.

This is the full-width element which contains the text-bearing element and any icons.

Note that column headers are rerendered upon mutation of Column values, so this value is volatile and should not be cached, but should be read whenever needed.

Get/set columns width in px. If column uses flex, width will be undefined. Setting a width on a flex column cancels out flex.

NOTE: Grid might be configured to always stretch the last column, in which case the columns actual width might deviate from the configured width.

let grid = new Grid({
    appendTo : 'container',
    height   : 200,
    width    : 400,
    columns  : [{
        text  : 'First column',
        width : 100
    }, {
        text  : 'Last column',
        width : 100 // last column in the grid is always stretched to fill the free space
    }]
});

grid.columns.last.element.offsetWidth; // 300 -> this points to the real element width

Has a corresponding width config.

The collapse behavior when collapsing a parent column. Specify "toggleAll" or "showFirst".

• "showFirst" toggles visibility of all but the first columns.

• "toggleAll" toggles all children, useful if you have a special initially hidden column which gets shown in collapsed state. To specify which columns are initially hidden, configure them with toggleAllHidden.

In the snippet below, the first two child columns are initially shown, while the third is initially hidden. When collapsing the parent column, the visibility of all three children will be toggled, so the third column will be shown and the first two hidden.

new Grid({
   columns : [{
         text        : 'Parent',
         collapsible : true,
         collapseMode : 'toggleAll',
         children    : [
             { text : 'Shown initially', field : 'field1', flex : 1 },
             { text : 'Shown initially', field : 'field2', flex : 1 },
             { text : 'Hidden initially', field : 'field3', flex : 1, toggleAllHidden : true }
         ]
   }]
});

{@note}Note that when using toggleAll mode, at least one child column must be configured with toggleAllHidden: true and at least one must not.{@/note}

Has a corresponding collapseMode config.

A config object used to create the input field which will be used for editing cells in the column. Used when CellEdit feature is enabled. The Editor refers to field for a data source.

Configure this as false or null to prevent cell editing in this column.

All subclasses of Field can be used as editors. The most popular are:

• TextField
• NumberField
• DateField
• TimeField
• Combo

If record has method set + capitalized field, method will be called, e.g. if record has method named setFoobar and the field is foobar, then instead of record.foobar = value, record.setFoobar(value) will be called.

Function may be used for React application parameter for using JSX components as editors.

 columns : [
        {
            type   : 'name',
            field  : 'name',
            width  : 250,
            editor : ref => <TextEditor ref={ref}/>
        },
        ...
]

where passing ref to the React editor is essential for the editor to work.

NOTE: React editor component must implement setValue method which usually internally calls setState. React setState is asynchronous so we need to return Promise which will be resolved when setState finishes. A typical example of setValue method implemented in a React editor is:

setValue(value) {
    return new Promise(resolve => this.setState({ value }, () => resolve(value)));
}

Please consult the React Integration Guide for details on usage of React cell editors.

Note that for Column subclasses which have a default editor, the editor config is merged with the Column class's default editor config. This allows an application to reconfigure the default editor to conform to requirements for a specific column:

new Grid({
    columns : [{
        type  : 'date',
        field : 'date',
        // Override defaults for the date editor
        editor : {
            step : null // disable back/forward stepping
        }
    }]
});

Has a corresponding editor config.

Allow filtering data in the column (if Filter or FilterBar feature is enabled).

Also allows passing a custom filtering function that will be called for each record with a single argument of format { value, record, [operator] }. Returning true from the function includes the record in the filtered set.

Configuration object may be used for FilterBar feature to specify filterField. See an example in the code snippet below or check FilterBar page for more details.

const grid = new Grid({
    columns : [
         {
             field : 'name',
             // Disable filtering for this column
             filterable : false
         },
         {
             field : 'age',
             // Custom filtering for this column
             filterable: ({ value, record }) => Math.abs(record.age - value) < 10
         },
         {
             field : 'start',
             // Changing default field type
             filterable: {
                 filterField : {
                     type : 'datetime'
                 }
             }
         },
         {
             field : 'city',
             // Filtering for a value out of a list of values
             filterable: {
                 filterField : {
                     type  : 'combo',
                     value : '',
                     items : [
                         'Paris',
                         'Dubai',
                         'Montreal',
                         'London',
                         'New York'
                     ]
                 }
             }
         },
         {
             field : 'score',
             filterable : {
                 // This filter fn doesn't return 0 values as matching filter 'less than'
                 filterFn : ({ record, value, operator, property }) => {
                     switch (operator) {
                         case '<':
                             return record[property] === 0 ? false : record[property] < value;
                         case '=':
                             return record[property] == value;
                         case '>':
                             return record[property] > value;
                     }
                 }
             }
         }
    ]
});

When providing a custom filtering function, if the filter feature is configured with prioritizeColumns : true that function will also be used for programmatic filtering of the store:

const grid = new Grid({
    features : {
        filter : {
            prioritizeColumns : true
        }
    },

    columns : [
         {
             field : 'age',
             // Custom filtering for this column
             filterable: ({ value, record }) => Math.abs(record.age - value) < 10
         }
    ]
});

// Will use filterable() from the column definition above
grid.store.filter({
    property : 'age',
    value    : 50
});

To use custom FilterField combo store it should contain one of these data or readUrl configs. Otherwise combo will get data from owner Grid store.

const grid = new Grid({
    columns : [
         {
             field : 'name',
             filterable: {
                 filterField {
                     type  : 'combo',
                     store : new Store({
                         data : ['Adam', 'Bob', 'Charlie']
                     })
                 }
             }
         }
    ]
});

or

const grid = new Grid({
    columns : [
         {
             field : 'name',
             filterable: {
                 filterField : {
                    type  : 'combo',
                    store : new AjaxStore({
                        readUrl  : 'data/names.json',
                        autoLoad : true
                    })
                 }
             }
         }
    ]
});

Has a corresponding filterable config.

A function which is called when a cell edit is requested to finish.

This may be an async function which performs complex validation. The return value should be:

• false - To indicate a generic validation error
• true - To indicate a successful validation, which will complete the editing
• a string - To indicate an error message of the failed validation. This error message will be cleared upon any subsequent user input.

The action for the failed validation is defined with the invalidAction config.

For example for synchronous validation:

const grid = new Grid({
   columns : [
      {
         type : 'text',
         text : 'The column',
         field : 'someField',
         flex : 1,
         finalizeCellEdit : ({ value }) => {
             return value.length < 4 ? 'Value length should be at least 4 characters' : true;
         }
      }
   ]
});

Here we've defined a validation finalizeCellEdit function, which marks all edits with new value less than 4 characters length as invalid.

For asynchronous validation you can make the validation function async:

finalizeCellEdit : async ({ value }) => {
    return await performRemoteValidation(value);
}

Has a corresponding finalizeCellEdit config.

By default, cell editing is finalized when the editor is blurred or if the user taps outside the editor. For complex custom editors, focus or tapping might be expected outside the Bryntum owned editor. In such cases, supply false for this config to take manual control over when cell editing in the column should be finalized.

To accept changes, call finishEditing. To reject, call cancelEditing.

// Setup
const grid = new Grid({
  columns : [
    {
      text               : 'Skills',
      field              : 'skills',
      managedCellEditing : false
    }
  ]
});

// From your custom editor, when you are ready to accept changes
grid.finishEditing();

Has a corresponding managedCellEditing config.

Allow sorting of data in the column. You can pass true/false to enable/disable sorting, or provide a custom sorting function, or a config object for a CollectionSorter

const grid = new Grid({
    columns : [
         {
             // Disable sorting for this column
             sortable : false
         },
         {
             field : 'name',
             // Custom sorting for this column
             sortable(user1, user2) {
                 return user1.name < user2.name ? -1 : 1;
             }
         },
         {
             // A config object for a Core.util.CollectionSorter
             sortable : {
                 property         : 'someField',
                 direction        : 'DESC',
                 useLocaleCompare : 'sv-SE'
             }
         }
    ]
});

When providing a custom sorting function, if the sort feature is configured with prioritizeColumns : true that function will also be used for programmatic sorting of the store:

const grid = new Grid({
    features : {
      sort : {
          prioritizeColumns : true
      }
    },

    columns : [
         {
             field : 'name',
             // Custom sorting for this column
             sortable(user1, user2) {
                 return user1.name < user2.name ? -1 : 1;
             }
         }
    ]
});

// Will use sortable() from the column definition above
grid.store.sort('name');

Also, any custom sorter function is called with an additional parameter indicating the sort direction. Please note that is an informative parameter, the result of the sort function is already reversed if needed depending on direction.

const grid = new Grid({
    columns : [
         {
             field : 'name',
             // direction will be ASC or DESC
             sortable(user1, user2, direction) {
                 return user1.name < user2.name ? -1 : 1;
             }
         }
    ]
});

Has a corresponding sortable config.

Only applies for leaf columns in a collapsible group configured with collapseMode : 'toggleAll'. Specify true to show the column when the group is collapsed, false to hide it.

See collapseMode for more details and an example.

Has a corresponding toggleAllHidden config.

Region (part of the grid, it can be configured with multiple) where to display the column. Defaults to defaultRegion.

A column under a grouped header automatically belongs to the same region as the grouped header.

Has a corresponding region config.

Extra items to show in the cell context menu for this column, null or false to not show any menu items for this column.

cellMenuItems : {
    customItem : { text : 'Custom item' }
}

Has a corresponding cellMenuItems config.

Extra items to show in the header context menu for this column.

// A rank column, which displays its header text vertically and offers a menu item to toggle that
{
    text              : 'Rank',
    field             : 'rank',
    width             : 30,
    type              : 'number',
    headerWritingMode : 'sideways-lr',
    align             : 'center',
    headerMenuItems   : {
        toggleVerticalText : {
            text    : 'Vertical header text',
            checked : true,
            weight  : 10,
            onItem  : ({ column }) => {
                column.headerWritingMode = column.headerWritingMode ? null : 'sideways-lr';
            }
        }
    }
},

Has a corresponding headerMenuItems config.

Specify true to merge cells within the column whose value match between rows, making the first occurrence of the value span multiple rows.

Only applies when using the MergeCells feature.

This setting can also be toggled using the column header menu.

Has a corresponding mergeCells config.

Set to false to prevent merging cells in this column using the column header menu.

Only applies when using the MergeCells feature.

Has a corresponding mergeable config.

An empty function by default, but provided so that you can override it. This function is called each time a merged cell is rendered. It allows you to manipulate the DOM config object used before it is synced to DOM, thus giving you control over styling and contents.

NOTE: The function is intended for formatting, you should not update records in it since updating records triggers another round of rendering.

const grid = new Grid({
  columns : [
    {
      field      : 'project',
      text       : 'Project',
      mergeCells : 'true,
      mergedRenderer({ domConfig, value, fromIndex, toIndex }) {
        domConfig.className.highlight = value === 'Important project';
      }
   }
 ]
});

Has a corresponding mergedRenderer config.

Set to false to not always clear cell content if the renderer returns undefined or has no return statement. This is useful when you mutate the cellElement, and want to prevent cell content from being reset during rendering.

Set to true to always clear cell content regardless of renderer return value.

Has a corresponding alwaysClearCell config.

An array of the widgets to append to the column header. These widgets have this Column instance as their owner which can be used to reference the column, and the owning Grid via this.owner.grid.

columns : [
{
    text          : 'Name',
    field         : 'name',
    flex          : 1,
    headerWidgets : [
        {
            type      : 'button',
            text      : 'Add row',
            rendition : 'filled',
            async onAction() {
                const
                     grid = this.owner.grid,
                     [newRecord] = grid.store.add({
                         name : 'New user'
                     });

                await grid.scrollRowIntoView(newRecord);

                await grid.features.cellEdit.startEditing({
                    record : newRecord,
                    field  : 'name'
                });
            }
        }
    ]
}]

Has a corresponding headerWidgets config.

Applies a CSS class that controls the CSS writing-mode property for the column header text element.

{
    text              : 'Rank',
    field             : 'rank',
    width             : 30,
    type              : 'number',
    headerWritingMode : 'sideways-lr'
}

Has a corresponding headerWritingMode config.

A callback function called after every cell has been rendered, which lets you mutate the cell/row or contents. This is useful when you want to mutate contents of a pre-configured column (e.g. CheckColumn, WidgetColumn etc.) without overwriting the built-in renderer.

In the method, you can modify the cell / row elements, e.g. to add custom CSS classes:

new Grid({
    columns : [
        {
            text     : 'Name',
            afterRenderCell : ({ record, row, cellElement }) => {
                cellElement.classList.toggle('myClass', true);
                // Add special CSS class to new rows that have not yet been saved
                row.cls.newRow = record.isPhantom;
            }
        }
    ]
});

Has a corresponding afterRenderCell config.

Renderer function for group headers (when using Group feature).

const grid = new Grid({
    columns : [
        {
            text : 'ABC',
            groupRenderer(renderData) {
                return {
                     class : {
                         big   : true,
                         small : false
                     },
                     children : [
                         { tag : 'img', src : 'img.png' },
                         renderData.groupRowFor
                     ]
                };
            }
        }
    ]
});

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding groupRenderer config.

Renderer function for the column header.

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding headerRenderer config.

Renderer function, used to format and style the content displayed in the cell. Return the cell text you want to display. Can also affect other aspects of the cell, such as styling.

new Grid({
    columns : [
        { text : 'Status', renderer : ({ record }) => record.status }
    ]
});

You can also return a DomConfig object describing the markup:

new Grid({
    columns : [
        {
             text : 'Status',
             renderer : ({ record }) => {
                 return {
                     class : 'myClass',
                     children : [
                         {
                             tag : 'i',
                             class : 'fa fa-pen'
                         },
                         {
                             tag : 'span',
                             text : record.name
                         }
                     ]
                 };
             }
        }
    ]
});

You can modify the row element too from inside a renderer to add custom CSS classes:

new Grid({
    columns : [
        {
            text     : 'Name',
            renderer : ({ record, row }) => {
               // Add special CSS class to new rows that have not yet been saved
              row.cls.newRow = record.isPhantom;

              return record.name;
        }
    ]
});

If you are adding a renderer to a column that has a built in renderer (like DateColumn or NumberColumn), you may call the built-in renderer from your custom renderer if you want to use the default content and modify it. For example, to highlight modified dates in a DateColumn:

new Grid({
    columns : [
        {
            type     : 'date',
            field    : 'startDate',
            text     : 'Start Date',
            renderer : ({ record, column }) => {
                let result = this.defaultRenderer(...arguments);

                // Highlight modified start dates
                if (record.isFieldModified('startDate')) {
                    result = `<span class="modified">${result}</span>`;
                }
                return result;
            }
        }
    ]
});

Using JSX (React)

When using the Bryntum React wrapper, renderers can return JSX elements:

renderer({ record, value }) {
    return <MyComponent value={value} record={record} />;
}

{@note}When renderer includes static HTML output, htmlEncode will be automatically set to false if not explicitly configured. You are responsible for HTML encoding user-provided data to mitigate XSS issues. See StringHelper.encodeHtml.{@/note}

Has a corresponding renderer config.

Controls stickiness when the StickyCells feature is enabled.

• true (default) - all cell content is pinned while the row scrolls off the top
• false - this column is excluded from stickiness
• A CSS selector string - only the matching child element is pinned

// Only pin the date header inside each cell
{ stickyContent : '.my-date-header' }

Has a corresponding stickyContent config.

Renderer function for the cell tooltip (used with CellTooltip feature). Specify false to disable tooltip for this column.

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding tooltipRenderer config.

Renderer function for summary (when using Summary feature). The renderer is called with an object having the calculated summary sum parameter. Function returns a string value to be rendered.

Example:

columns : [{
    type            : 'number',
    text            : 'Score',
    field           : 'score',
    sum             : 'sum',
    summaryRenderer : ({ sum }) => `Total amount: ${sum}`
}]

When using the Bryntum React wrapper, this renderer can also return JSX elements. See renderer for a JSX example and performance considerations.

Has a corresponding summaryRenderer config.