You are viewing documentation for Vaadin Framework 8 and related products View documentation for Vaadin Framework 7 ›
Configuring Columns · Vaadin
Vaadin Elements - Grid - Configuring Columns

Configuring Columns

This section describes configuration options for the columns in vaadin-grid.

Defining the Columns

You can define the columns in a vaadin-grid with col elements. These elements should be placed inside a colgroup wrapper inside a table element.

To define the captions of the columns, you should use th elements inside a table row wrapped in a thead element. See the following example for a simple two-column configuration.

<vaadin-grid>
  <table>
    <colgroup>
      <col>
      <col>
    </colgroup>
    <thead>
      <tr>
        <th>First column</th>
        <th>Second column</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>One</td>
        <td>Two</td>
      </tr>
    </tbody>
  </table>
</vaadin-grid>

An alternative way to define the columns is to use the JavaScript API. You can modify the columns through the grid.columns array.

// Columns can also be configured in JavaScript.
grid.columns = [
  { name: "firstColumn" },
  { name: "secondColumn" }
];

Adding and Removing Columns Dynamically

The vaadin-grid element has a JavaScript API for dynamically inserting and removing columns. To add a column, you can use the addColumn() method, which takes a column object and an optional index or column name as its parameters.

// Add a column as the last column of the grid.
grid.addColumn({name: 'secondColumn'});

// Specify the index or name of the column before which to add the new column.
grid.addColumn({name: 'firstColumn'}, 0);

In order to remove columns, there is a method called removeColumn(), which takes the column index or name as a parameter.

// Remove the first column of the grid.
grid.removeColumn(0);

// Remove the second column of the grid.
grid.removeColumn('secondColumn');

Defining Column Widths

By default all the columns share the available size equally. You can use the column.flex property to adjust how much a column spans in width relative to other columns. Columns may also be assigned an explicit width, a maximum width and a minimum width with column.width, column.maxWidth, and column.minWidth properties.

<vaadin-grid>
  <table>
    <colgroup>
      <col width="100" flex="1">
      <col max-width="200" flex="2">
      <col min-width="100" flex="1">
    </colgroup>
    <!-- ... -->
  </table>
</vaadin-grid>
// Setting the width properties with JavaScript API.
grid.columns[0].width = 100;
grid.columns[1].maxWidth = 200;
grid.columns[2].minWidth = 100;

// Setting the flex properties with JavaScript API.
grid.columns[0].flex = 1;
grid.columns[1].flex = 2;
grid.columns[2].flex = 1;

Frozen Columns

A number of columns starting from the left may be set as "frozen". The setting forces them to remain horizontally still while the rest of the columns scroll normally.

You can do this by setting the number of frozen columns in the grid.frozenColumns property or declaratively using the frozen-columns attribute. In multi-select mode, the selection column, which contains the checkboxes, is frozen by default. Setting grid.frozenColumns to -1 will unfreeze it as well.

// Define a single column to be frozen
grid.frozenColumns = 1;

Hiding Columns

Columns can be either hidden or visible, which is determined by the column.hidden property. Another property called column.hidable can be used to make some columns hidable by the user. Setting a column’s hidable property to true includes it in a drop-down menu on the right side of the column headers, where individual columns can be toggled hidden/visible by the user.

vaadin grid column hiding
Figure 1. User can toggle column visibility with the drop-down
<vaadin-grid>
  <table>
    <colgroup>
      <col>
      <col hidable>
      <col hidable hidden>
      <col hidden>
    </colgroup>
    <!-- ... -->
  </table>
</vaadin-grid>
// Setting the properties with JS API
grid.columns[1].hidable = true;
grid.columns[2].hidable = true;
grid.columns[2].hidden = true;
grid.columns[3].hidden = true;

See the live example.

Column Reordering

The end users can reorder non-frozen columns by dragging the header cells. By default, column reordering is disabled, but it can be enabled by setting the columnReorderingAllowed property to true.

Column reordering works only when the data source is based on objects bound to the column configuration using the name attribute. Usage of object values is described in section Using Object Values.

When using arrays as data, you need to take care of reordering the data after the column order is changed. You will get notified of this by listening to the column-order-changed event.

vaadin grid column reordering
Figure 2. User can drag the header cells to reorder the columns
<vaadin-grid column-reordering-allowed>
  <!-- ... -->
</vaadin-grid>
// Setting the property with JS API
grid.columnReorderingAllowed = true;
// Listening to column order changes
grid.addEventListener('column-order-changed', function() {
  var columnNames = grid.columns.map(function(col) { return col.name; });
  console.log('Column order is now: ' + columnNames.join(', '));
});

See the live example.

Column Resizing

Columns can be resized by dragging the separation line in headers. By default it is disabled. Set the column.resizable property to a column to make it resizable.

When a column is resized, you will get notified by listening to the column-resized event.

vaadin grid column resizing
Figure 3. User can drag the header separator to resize the column.
<vaadin-grid>
  <table>
    <colgroup>
      <col>
      <col resizable>
    </colgroup>
    <!-- ... -->
  </table>
</vaadin-grid>
// Setting the properties with JS API
grid.columns[0].resizable = false;
grid.columns[1].resizable = true;

See the live example.