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

Assigning Data

In this section, we will show you how to get started with assigning data to your vaadin-grid. We will go through the basics of using HTML and JSON objects to generate a grid that looks like in A vaadin-grid displaying data with three columns.

vaadin grid assigning data
Figure 1. A vaadin-grid displaying data with three columns

For more advanced data assignment topics, see Lazy Loading and Remote Data.

Using Data from an HTML Table

The easiest way to assign data into vaadin-grid is to use an HTML table. To get started, you can take any existing table element and place it inside the vaadin-grid element.

To define the number of columns displayed, you need to insert col elements inside the table element. You can wrap them inside a colgroup element as in the example below, but that is optional. Headers for each column can be configured using th elements in the thead section.

<vaadin-grid>
  <table>
    <colgroup>
      <col>
      <col>
      <col>
    </colgroup>
    <thead>
      <tr>
        <th>First</th>
        <th>Last</th>
        <th>Email</th>
      </tr>
    </thead>
    <tbody>
      <tr>
        <td>amber</td>
        <td>crawford</td>
        <td>[email protected]</td>
      </tr>
      <tr>
        <td>zoe</td>
        <td>caldwell</td>
        <td>[email protected]</td>
      </tr>
      <tr>
        <td>jessie</td>
        <td>brooks</td>
        <td>[email protected]</td>
      </tr>
      <tr>
        ...
      </tr>
    </tbody>
  </table>
</vaadin-grid>

Using Object Values

When using objects as data, you can provide the array of objects to vaadin-grid.

First, you need to define the columns and a mapping between object properties and the columns. You can do this using the col elements and its name attribute, as in the example below.

<vaadin-grid>
  <table>
    <colgroup>
      <col name="user.name.first">
      <col name="user.name.last">
      <col name="user.email">
    </colgroup>
  </table>
</vaadin-grid>

Optionally, you can dismiss the whole table element and configure the columns using the JavaScript API. See the following example and also Configuring Columns for more details.

grid.columns = [
  { name: 'user.name.first' },
  { name: 'user.name.last' },
  { name: 'user.email' }
];

If you do not provide a thead element for the header, headers will be automatically generated from the name attributes, as described in Customizing Headers and Footers.

After you have configured the columns, you can go ahead and assign the data array to the items property of the grid.

grid.items = [
  {
    user: {
      name: { first: 'amber', last: 'crawford' },
      email: '[email protected]'
    }
  },
  {
    user: {
      name: { first: 'zoe', last: 'caldwell' },
      email: '[email protected]'
    }
  },
  {
    user: {
      name: { first: 'jessie', last: 'brooks' },
      email: '[email protected]'
    }
  }
  ...
];

See the live example.

Using Primitive Values

When your data consists of primitive values, columns are mapped by indexes instead of the name property.

First, you need to define a column by a col element without a name attribute, as done in the following example, or by using the JavaScript API, as described in Configuring Columns.

The header auto generation does not apply here because we are missing the name property, so you also have to define a thead element.
<vaadin-grid>
  <table>
    <colgroup>
      <col>
    </colgroup>
    <thead>
      <tr>
        <th>First Name</th>
      </tr>
    </thead>
  </table>
</vaadin-grid>

After you have configured the columns, you can go ahead and assign the data.

grid.items = ['amber', 'zoe', 'jessie', 'eva', ...]

In case you need more than one column, add another pair of col and th elements and provide the data using nested arrays.

grid.items = [
  ['amber', 'crawford'],
  ['zoe', 'caldwell'],
  ['jessie', 'brooks'],
  ...
]

See the live example.

Using Dynamic Data

If the data can change dynamically, vaadin-grid must be notified of the changes.

You can define the size of the active dataset with the size property of vaadin-grid. If you add or remove items, you need to update the size accordingly. Like any other property, size can also be applied as an attribute.

<vaadin-grid size="100"></vaadin-grid>
When using arrays as data, the length of the original item array is set as the initial size.
// In this case, grid.items.push(...); would do the same,
// but using grid.push('items', ...); is preferred.
grid.push('items', {
  user: {
    name: { first: 'eva', last: 'burke' }, email: '[email protected]'
  }
});

// Increase the size after pushing a new item.
grid.size++;

If the data changes, you need to call refreshItems(). The refreshItems() method is used to trigger vaadin-grid to refresh the displayed data.

grid.items[0].email = '[email protected]';
grid.refreshItems();

See the live example.