Migration from 1.* to 2.0

Sauli Tähkäpää edited this page Apr 7, 2017 · 36 revisions

Migrating from <vaadin-grid> 1.x to 2.0

This document will summarize the biggest differences you need to take into consideration when migrating from 1.x to 2.0.

In case you feel there is something missing or you want to ask about, head over to our Chat.

You can also file issues at the <vaadin-grid> repository

Important Links

v2.0.0 API Documentation

v2.0.0 Demos

Notable Changes

Assigning Data

  • <table> is not longer used to configure data rows or columns. <vaadin-grid-column> are used instead.
  • items property is now split into items and dataProvider properties.

Customizing Headers and Footers

  • Instead of defining a <thead> or a <tfoot>, header and footer templates are used for each <vaadin-grid-column>.
  • For multirow headers and footers, <vaadin-grid-column-group> is used.


  • Every column has an explicit width. The content in the column no longer affects the width. The default width is 100 pixels. The width can be any valid CSS value (percentages for example), unlike in 1.x where it can only be pixels.
  • The width property also acts as the flex-basis of the columns, i.e. how the unused horizontal space is distributed among the columns.
  • flex property is renamed to flexGrow, and it only affects how extra space is distributed for the column. The columns will no longer shrink below their specified width (no flex-shrink behavior), unless resized by the end user.
  • minWidth and maxWidth properties are removed. The width property acts as the minimum width (but does not affect end user resizing).
  • hidable property is removed. There is no longer a built-in menu for toggling the visibility of columns. This can be implemented as a custom element (which you can place in the header cells of the grid) which toggles the hidden property of the columns.
  • sortable property is removed. Place <vaadin-grid-sorter> elements inside column header templates instead.


  • The concept of "Selection Mode" is dropped.
  • Selection is always "enabled", but it needs to be separately defined how user will select rows, see selection
  • Instead of item indexes, selectedItems contains the selected item objects.

Data Formatting

  • Instead of renderer functions, templates inside <vaadin-grid-column> elements are used.


  • Instead of cell and row class generators, style mixins and custom classes inside templates are used.
  • Template contents are now also available for plain CSS styling, also when native Shadow DOM is used.

Row Details

  • Instead of generator functions, row details template is used.

Visual styles

API Changes

Styling Mixins

--vaadin-grid-row-height Removed

  • Apply the desired cell height to your body cell contents.
  • Alternatively, use --vaadin-grid-body-cell to apply height to all body cells.

--vaadin-grid-header-row-height Removed

  • Apply the desired cell height to your header cell contents.
  • Alternatively, use --vaadin-grid-header-cell to apply height to all header cells.

--vaadin-grid-footer-row-height Removed

  • Apply the desired cell height to your footer cell contents.
  • Alternatively, use --vaadin-grid-footer-cell to apply height to all footer cells.

--vaadin-grid-selected-row-cell Renamed

  • Use --vaadin-grid-body-row-selected-cell for applying styles to body cells on selected rows.

--vaadin-grid-row-cell Renamed

  • Use --vaadin-grid-body-cell for applying styles to body cells.

--vaadin-grid-row-stripe-cell Renamed

  • Use --vaadin-grid-body-row-odd-cell for applying styles to body cells on odd rows.

Properties and Attributes

columns Removed

  • To modify columns dynamically, add and remove <vaadin-grid-column> elements under <vaadin-grid>.
  • See Live Example

detailedEvents Removed

  • detailsEvents was originally targeted to be used together with <vaadin-context-menu> – in 2.0 you are able access the contents more flexibly, so there isn't a need for this event anymore.
  • See Live Examples

disabled Removed

footer Removed

  • Use <template class="footer"> to customize and access footer cell contents.
    <template class="footer">
      <div>Total Number of 100</div>

frozenColumns Removed

  • Use frozen property on <vaadin-grid-column> to freeze columns.
  <vaadin-grid-column frozen>
  • frozen can be also applied on <vaadin-grid-column-group> elements.
  • Columns marked with frozen are frozen in-place – to get an expected outcome, freeze columns starting from left.
  • See Live Example

header Removed

  • Use <template class="header"> to customize and access header cell contents.
    <template class="header">First Name</template>

items Changed

  • Use items to add an array data source. Works similarly to 1.x.
<iron-ajax url="https://randomuser.me/" last-response="{{response}}" auto></iron-ajax>
<vaadin-grid items="[[response.results]]">
  • Use dataProvider (dataSource in v2.0.0-alpha2 or older) in later to add a function data source. Remember to set also the size property to reflect the size of the dataset.

selection Changed

  • Use {{selected}} template variable and selectedItems array to modify selection.
    • selectedItems contains items instead of indexes.
    • grid.push('selectedItems', item), grid.pop('selectedItems'), grid.splice('selectedItems' ...) can be used.
    • selectItem(item) and deselectItem(item) are also available.
  • Use selectedItems.length for the size of the selection.
  • Assign an empty array to selectedItems to clear the selection.
  • Copy items to selectedItems to select all items.
  • See Live Example

sortOrder Removed

  • Use <vaadin-grid-sorter> elements to access and control sorting.
  • For items array, <vaadin-grid-sorter> provides built-in sorting.
  • For dataProvider, sortOrder is provided in options given to the provider function.
  • See Live Example

visibleRows Removed


addColumn Removed

  • To add columns dynamically, append <vaadin-grid-column> elements inside <vaadin-grid>.
  • See columns

cellClassGenerator Removed

  • To customize cell contents, apply custom classes to elements inside cell templates.
  • See Live Example

getItem Removed

  • Loaded items can be accessed directly from selectedItems, expandedItems or through event listeners in the cells. See Live Example
  • To fetch a specific item from your data source, use a data source provided method.

refreshItems Renamed

  • Use clearCache() to clear the cached pages and reload data from data source.

removeColumn Removed

  • To remove columns dynamically, remove <vaadin-grid-column> elements from under <vaadin-grid>.
  • See columns

rowClassGenerator Removed

  • To customize cell contents, apply custom classes to elements inside cell templates.
  • For adding "striped" row styles, you can use the --vaadin-grid-body-row-odd-cell mixin.
  • See Live Example

rowDetailsGenerator Removed

  • Use <template class="row-details"> to customize the row detail cell contents.

scrollToEnd Removed

scrollToRow Removed

scrollToStart Removed

setRowDetailsVisible Removed

  • Use {{expanded}} template variable or modify expandedItems property.
  • See Live Example

then Removed

  • In <vaadin-grid> 1.x, then() was used to wait until some asynchronous actions, like reading column information from DOM were completed. In 2.0, columns are read synchronously from DOM, and for every asynchronous action there is a callback or an event.


column-order-changed Removed

column-resized Removed

  • Listen to column-width-changed for column width notifications.

detailed-event Removed

selection-mode-changed Removed

sort-order-changed Removed

  • Use <vaadin-grid-sorter> elements directly.
Clone this wiki locally
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.