Documentation

Grid

API: TypeScript / Java

Source: TypeScript / Java

Vaadin Grid is a component for displaying tabular data, including various enhancements to grid renderings.

Content
Dynamic Height
Selection
Columns
Sorting
Filtering
Lazy Loading
Item Details
Context Menu
Tooltips
Drag & Drop
Inline Editing (Java Only)
Styling Rows & Columns Dynamically
Styling Header & Footer Cells
Theme Variants
Cell Focus
Related Components

Vaadin Grid is a component for displaying tabular data, including various enhancements to grid renderings.

In the first example here, you can see a very basic example of a grid. A user can’t do much with it — other than scroll through the rows of data. However, Vaadin Grid has many features that may be enabled to allow the user to do plenty more. It can display the data in better ways, depending on its dynamic content.

The following sections describe these features. They include functioning examples of each feature on which you may try them: You can drag and drop, resort, and edit data.

Open in a
new tab

@state()
private accessor items: Person[] = [];

protected override async firstUpdated() {
  const { people } = await getPeople();
  this.items = people;
}

protected override render() {
  return html`
    <vaadin-grid .items="${this.items}">
      <vaadin-grid-column path="firstName"></vaadin-grid-column>
      <vaadin-grid-column path="lastName"></vaadin-grid-column>
      <vaadin-grid-column path="email"></vaadin-grid-column>
      <vaadin-grid-column path="profession"></vaadin-grid-column>
    </vaadin-grid>
  `;
}

Content

A basic grid uses plain text to display information in rows and columns. Rich content can be included to provide additional information for more legibility. Components such as Text Field, Date Picker, Select, and Button are also supported.

Notice how much nicer and richer the grid content is rendered in the table below compared to the first example:

Open in a
new tab

@state()
private accessor items: Person[] | undefined;

protected override async firstUpdated() {
  const { people } = await getPeople();
  this.items = people;
}

protected override render() {
  return html`
    <vaadin-grid .items="${this.items}">
      <vaadin-grid-selection-column></vaadin-grid-selection-column>
      <vaadin-grid-column
        header="Employee"
        flex-grow="0"
        auto-width
        ${columnBodyRenderer(this.employeeRenderer, [])}
      ></vaadin-grid-column>
      <vaadin-grid-column path="profession" auto-width></vaadin-grid-column>
      <vaadin-grid-column
        header="Status"
        auto-width
        ${columnBodyRenderer(this.statusRenderer, [])}
      ></vaadin-grid-column>
    </vaadin-grid>
  `;
}

private employeeRenderer: GridColumnBodyLitRenderer<Person> = (person) => html`
  <vaadin-horizontal-layout style="align-items: center;" theme="spacing">
    <vaadin-avatar
      img="${person.pictureUrl}"
      name="${person.firstName} ${person.lastName}"
      alt="User avatar"
    ></vaadin-avatar>
    <vaadin-vertical-layout style="line-height: var(--lumo-line-height-m);">
      <span>${person.firstName} ${person.lastName}</span>
      <span style="font-size: var(--lumo-font-size-s); color: var(--lumo-secondary-text-color);">
        ${person.email}
      </span>
    </vaadin-vertical-layout>
  </vaadin-horizontal-layout>
`;

private statusRenderer: GridColumnBodyLitRenderer<Person> = ({ status }) => html`
  <span theme="badge ${status === 'Available' ? 'success' : 'error'}">${status}</span>
`;

Component vs. Lit Renderer (Flow Only)

As shown in the earlier example, custom content can be rendered using component renderers or Lit renderers. They each have their advantages, but also some drawbacks compared to each other.

Component Renderer

Component renderers are easy to build, but slow to render. They generate a component for each item in the dataset for a given column. The rendered components are fully controllable on the server side.

For each rendered cell, Grid creates a corresponding component instance on the server side. A dataset of 100 items with 10 columns using a component renderer produces up to 1,000 components that need to be managed. The more components you use in a component renderer, the greater the impact on performance.

Component renderers are very flexible and easy to use, but they should be used with caution. They’re better suited as editors since only a single row can be edited at a time. They can also be used for detail rows.

Lit Renderer

Lit renders quickly, but requires you to write HTML code. To use components with Lit renderers, you need to use their HTML format. Lit templates are immutable: the state of the components can’t be managed on the server side. However, the template can have different representations, depending on the state of the item.

The only data sent from the server — other than the template itself, which is sent only once — is the extra name property of each item.

Lit templates still enable event handling on the server side. However, you can’t, for example, disable or change the text of a button from the event handler. For such situations, use an editor instead.

With Lit renderers, the server doesn’t keep track of the components in each cell. It only manages the state of the items in each row. The client doesn’t have to wait for the server to send missing information about what needs rendering. It can use the template to render all of the cells it requires.

For in-depth information on how to use Lit renderers with Flow, see the Using Lit Renderers with Grid page of this documentation.

Wrap Cell Content

Cell content that overflows is normally clipped or truncated. However, the wrap-cell-content variant makes the content wrap instead.

Notice in the example here that the text in the Address cells is wrapped. If you click on the gray icon at the top right corner of the example, it opens the table in a separate browser tab. When you do that, can see the addresses on one line. You can also resize that window to see how it wraps and unwraps the text.

Open in a
new tab

@customElement('grid-wrap-cell-content')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people;
  }

  protected override render() {
    return html`
      <vaadin-grid .items="${this.items}" theme="wrap-cell-content">
        <vaadin-grid-column
          header="Image"
          flex-grow="0"
          auto-width
          ${columnBodyRenderer(this.avatarRenderer, [])}
        ></vaadin-grid-column>
        <vaadin-grid-column path="firstName"></vaadin-grid-column>
        <vaadin-grid-column path="lastName"></vaadin-grid-column>
        <vaadin-grid-column
          header="Address"
          ${columnBodyRenderer(this.addressRenderer, [])}
        ></vaadin-grid-column>
      </vaadin-grid>
    `;
  }

  private avatarRenderer: GridColumnBodyLitRenderer<Person> = (person) => html`
    <vaadin-avatar
      img="${person.pictureUrl}"
      name="${person.firstName} ${person.lastName}"
      alt="User avatar"
    ></vaadin-avatar>
  `;

  private addressRenderer: GridColumnBodyLitRenderer<Person> = ({ address }) => html`
    <span>${address.street} ${address.city} ${address.zip} ${address.state}</span>
  `;
}

Tooltips can also be used to display content that doesn’t fit into the cell.

Dynamic Height

Grid has a default height of 400 pixels. It becomes scrollable when items contained in it overflow the allocated space.

In addition to setting any fixed or relative value, the height of a grid can be set by the number of items in the dataset. The grid expands and retracts based on the row count. This feature disables scrolling. It shouldn’t be used with large data sets since it might cause performance issues.

Notice how the height of the rows in the earlier example adjusts because of the text in the Address cells wrapping. With that in mind, click the gray icon at the top right corner of the example below to open it in a new browser tab. Try resizing it, making it narrower and then wider. Notice how the rows are always the same height and that the text doesn’t wrap. Instead, the text is truncated with ellipses.

Open in a
new tab

<vaadin-grid .items="${this.invitedPeople}" all-rows-visible>
  <vaadin-grid-column header="Name" path="displayName" auto-width></vaadin-grid-column>
  <vaadin-grid-column path="email"></vaadin-grid-column>
  <vaadin-grid-column path="address.phone"></vaadin-grid-column>
  <vaadin-grid-column
    header="Manage"
    ${columnBodyRenderer(this.manageRenderer, [])}
  ></vaadin-grid-column>
</vaadin-grid>

Selection

Selection isn’t enabled by default. Grid supports single- and multi-select. Single-select allows the user to select only one item, while multi-select permits multiple items to be selected.

Single-Selection Mode

In single-selection mode, the user can select and deselect rows by clicking anywhere on the row.

Open in a
new tab

@state()
private accessor items: Person[] = [];

@state()
private accessor selectedItems: Person[] = [];

protected override async firstUpdated() {
  const { people } = await getPeople();
  this.items = people;
}

protected override render() {
  return html`
    <vaadin-grid
      .items="${this.items}"
      .selectedItems="${this.selectedItems}"
      @active-item-changed="${(e: GridActiveItemChangedEvent<Person>) => {
        const item = e.detail.value;
        this.selectedItems = item ? [item] : [];
      }}"
    >
      <vaadin-grid-column path="firstName"></vaadin-grid-column>
      <vaadin-grid-column path="lastName"></vaadin-grid-column>
      <vaadin-grid-column path="email"></vaadin-grid-column>
    </vaadin-grid>
  `;
}

Multi-Select Mode

In multi-select mode, the user can use a checkbox column to select and deselect more than one row — not necessarily contiguous rows. Or the user can select all rows by clicking on the checkbox in the header row — and then un-check the ones they don’t want to be selected, rather than check many, individually.

Open in a
new tab

@customElement('grid-multi-select-mode')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people;
  }

  protected override render() {
    return html`
      <vaadin-grid .items="${this.items}">
        <vaadin-grid-selection-column></vaadin-grid-selection-column>
        <vaadin-grid-column path="firstName"></vaadin-grid-column>
        <vaadin-grid-column path="lastName"></vaadin-grid-column>
        <vaadin-grid-column path="email"></vaadin-grid-column>
      </vaadin-grid>
    `;
  }
}

Columns

Column alignment, freezing (i.e., fixed positioning), grouping, headers and footers, visibility, and width can be configured. Users can be allowed to resize and reorder columns.

Column Alignment

Three different column alignments are supported: left, which is the default; center; and right.

Right alignment is useful when comparing numeric values, as it helps with readability and scannability. Notice how the Amount column in the example here aligns the euro values to the right. Those values would be difficult to scan visually if they were left aligned or centered. Tabular numbers — if the font offers them — or a monospace font could be used to further improve digit alignment.

Open in a
new tab

<vaadin-grid .items="${this.items}">
  <vaadin-grid-column path="displayName" header="Name"></vaadin-grid-column>
  <vaadin-grid-column
    header="Due"
    ${columnBodyRenderer(() => html`<span>${this.randomDate()}</span>`, [])}
  ></vaadin-grid-column>
  <vaadin-grid-column
    header="Amount"
    text-align="end"
    ${columnBodyRenderer(
      () => html`
        <span style="font-variant-numeric: tabular-nums">${this.randomAmount()}</span>
      `,
      []
    )}
  ></vaadin-grid-column>
</vaadin-grid>

Column Freezing

Columns and column groups can be frozen — made sticky — to exclude them from horizontally scrolling a grid. This can be useful for keeping the most important columns always visible in a grid that contains so many columns they might otherwise scroll out of view. Freezing columns at the end of the grid is useful, for example, for keeping row actions always visible.

In the example here, try scrolling the data to the right and back left. Notice that the name of each person is stationary, so that you can see easily which data relates to which person as you scroll. The Edit button at the end also remains in place so that it’s available at any point while scrolling.

Open in a
new tab

<vaadin-grid-column
  frozen
  header="Name"
  auto-width
  flex-grow="0"
  ${columnBodyRenderer<Person>(
    (person) => html`${person.firstName} ${person.lastName}`,
    []
  )}
></vaadin-grid-column>
<vaadin-grid-column
  frozen-to-end
  auto-width
  flex-grow="0"
  ${columnBodyRenderer(
    () => html`<vaadin-button theme="tertiary-inline">Edit</vaadin-button>`,
    []
  )}
></vaadin-grid-column>

Although it’s technically possible to freeze any column, it should be used primarily to freeze columns at the start or end of the grid, leaving the remaining columns unfrozen.

Column Grouping

It’s possible to group columns together. They share a common header and footer. Use this feature to better visualize and organize related or hierarchical data.

In the example below, the first and last names are grouped under Name. Whereas, the street address, the city, and so forth are grouped under Address.

Open in a
new tab

@customElement('grid-column-grouping')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people;
  }

  protected override render() {
    return html`
      <vaadin-grid .items="${this.items}">
        <vaadin-grid-column-group header="Name">
          <vaadin-grid-column path="firstName"></vaadin-grid-column>
          <vaadin-grid-column path="lastName"></vaadin-grid-column>
        </vaadin-grid-column-group>
        <vaadin-grid-column-group header="Address">
          <vaadin-grid-column path="address.street"></vaadin-grid-column>
          <vaadin-grid-column path="address.city"></vaadin-grid-column>
          <vaadin-grid-column path="address.zip"></vaadin-grid-column>
          <vaadin-grid-column path="address.state"></vaadin-grid-column>
        </vaadin-grid-column-group>
      </vaadin-grid>
    `;
  }
}

Column Headers & Footers

Each column has a customizable header and footer. A basic column header shows the name in plain text. Footers are empty by default and therefore hidden. However, if you add content for the footer, it becomes visible. Incidentally, both the header and footer can contain rich content and components — notice the header and footer in the example here.

Open in a
new tab

@state()
private accessor items: Person[] = [];

protected override async firstUpdated() {
  const { people } = await getPeople();
  this.items = people.map((person) => ({
    ...person,
    displayName: `${person.firstName} ${person.lastName}`,
  }));
}

protected override render() {
  return html`
    <vaadin-grid .items="${this.items}">
      <vaadin-grid-column
        header="Name"
        path="displayName"
        ${columnFooterRenderer(() => html`<span>200 total members</span>`, [])}
      ></vaadin-grid-column>
      <vaadin-grid-column
        ${columnHeaderRenderer(this.subscriberHeaderRenderer, [])}
        ${columnBodyRenderer(this.subscriberRenderer, [])}
        ${columnFooterRenderer(() => html`<span>102 subscribers</span>`, [])}
      ></vaadin-grid-column>
      <vaadin-grid-column
        path="membership"
        ${columnHeaderRenderer(this.membershipHeaderRenderer, [])}
        ${columnFooterRenderer(() => html`<span>103 regular, 71 premium , 66 VIP</span>`, [])}
      ></vaadin-grid-column>
    </vaadin-grid>
  `;
}

private subscriberHeaderRenderer = () => html`
  <vaadin-horizontal-layout style="align-items: center;">
    <span>Subscriber</span>
    <vaadin-icon
      icon="vaadin:info-circle"
      title="Subscribers are paying customers"
      style="height: var(--lumo-font-size-m); color: var(--lumo-contrast-70pct);"
    ></vaadin-icon>
  </vaadin-horizontal-layout>
`;

private subscriberRenderer: GridColumnBodyLitRenderer<Person> = (person) =>
  html`<span>${person.subscriber ? 'Yes' : 'No'}</span>`;

private membershipHeaderRenderer = () => html`
  <vaadin-horizontal-layout style="align-items: center;">
    <span>Membership</span>
    <vaadin-icon
      icon="vaadin:info-circle"
      title="Membership levels determines which features a client has access to"
      style="height: var(--lumo-font-size-m); color: var(--lumo-contrast-70pct);"
    ></vaadin-icon>
  </vaadin-horizontal-layout>
`;

Column Visibility

When you want, columns and column groups can be hidden. You can provide the user with a menu for toggling column visibilities, for example, using Menu Bar. Allowing the user to hide columns is useful when only a subset of the columns is relevant to their task, and if there are plenty of columns.

In the example here, notice that the email address and telephone numbers are not fully visible because the data doesn’t wrap and won’t fit in the width provided. Now click on the Show/Hide Columns button to see a menu of choices to reduce the number of columns. Notice that all columns are checked. Deselect the First Name and then the Profession column. That should allow the email addresses and telephone numbers to be fully visible. Incidentally, if you don’t deselect any columns, you can still right-click on an email address to copy it: You’ll still get the whole address, even if it’s not visible.

Open in a
new tab

@state()
private accessor items: Person[] = [];

@state()
private accessor contextMenuItems: Array<ContextMenuItem & { key: string }> = [
  { text: 'First name', checked: true, key: 'firstName', keepOpen: true },
  { text: 'Last name', checked: true, key: 'lastName', keepOpen: true },
  { text: 'Email', checked: true, key: 'email', keepOpen: true },
  { text: 'Phone', checked: true, key: 'phone', keepOpen: true },
  { text: 'Profession', checked: true, key: 'profession', keepOpen: true },
];

protected override async firstUpdated() {
  const { people } = await getPeople();
  this.items = people;
}

protected override render() {
  return html`
    <vaadin-horizontal-layout style="align-items: baseline">
      <strong style="flex: 1;">Employees</strong>
      <vaadin-context-menu
        open-on="click"
        .items="${this.contextMenuItems}"
        @item-selected="${(e: ContextMenuItemSelectedEvent) => {
          const item = e.detail.value;
          item.checked = !item.checked;
          this.contextMenuItems = [...this.contextMenuItems];
        }}"
      >
        <vaadin-button theme="tertiary">Show/Hide Columns</vaadin-button>
      </vaadin-context-menu>
    </vaadin-horizontal-layout>

    <vaadin-grid .items="${this.items}">
      <vaadin-grid-column
        path="firstName"
        .hidden="${!this.contextMenuItems[0].checked}"
      ></vaadin-grid-column>
      <vaadin-grid-column
        path="lastName"
        .hidden="${!this.contextMenuItems[1].checked}"
      ></vaadin-grid-column>
      <vaadin-grid-column
        path="email"
        .hidden="${!this.contextMenuItems[2].checked}"
      ></vaadin-grid-column>
      <vaadin-grid-column
        path="address.phone"
        .hidden="${!this.contextMenuItems[3].checked}"
      ></vaadin-grid-column>
      <vaadin-grid-column
        path="profession"
        .hidden="${!this.contextMenuItems[4].checked}"
      ></vaadin-grid-column>
    </vaadin-grid>
  `;
}

Column Reordering & Resizing

Enabling the user to reorder columns is useful when they want to compare data that isn’t adjacent by default. Grouped columns can only be reordered within their group. Resizing is helpful when a column’s content doesn’t fit and is cut off or varies in length.

Instead of hiding columns as in the earlier example, in the example here the user can resize a truncated column to be able to read it, fully. Try doing that. Hover your mouse pointer over the space on the header row between the Street and City columns, until the mouse pointer changes to a resizing tool. Then, while holding the left mouse button, pull on the right edge of the Street column until you can see all of the street addresses.

Open in a
new tab

@customElement('grid-column-reordering-resizing')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people;
  }

  protected override render() {
    return html`
      <vaadin-grid .items="${this.items}" column-reordering-allowed>
        <vaadin-grid-column-group header="Name">
          <vaadin-grid-column path="firstName" resizable></vaadin-grid-column>
          <vaadin-grid-column path="lastName" resizable></vaadin-grid-column>
        </vaadin-grid-column-group>
        <vaadin-grid-column-group header="Address">
          <vaadin-grid-column path="address.street" resizable></vaadin-grid-column>
          <vaadin-grid-column path="address.city" resizable></vaadin-grid-column>
          <vaadin-grid-column path="address.zip" resizable></vaadin-grid-column>
          <vaadin-grid-column path="address.state" resizable></vaadin-grid-column>
        </vaadin-grid-column-group>
      </vaadin-grid>
    `;
  }
}

Column Width

Unless specified, all columns are the same width. You can set a specific width for any column, though, or allow the Grid to set the width based on the content. Column widths can be fixed or non-fixed, which is the default. Fixed-width columns don’t grow or shrink as the available space changes, while non-fixed-width columns do.

In the following example, the first and last columns have fixed widths. The second column’s width is set to be based on the content, while the third column takes up the remaining space.

Open in a
new tab

@customElement('grid-column-width')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people;
  }

  protected override render() {
    return html`
      <vaadin-split-layout>
        <vaadin-grid .items="${this.items}" style="width: 100%;">
          <vaadin-grid-selection-column></vaadin-grid-selection-column>
          <vaadin-grid-column path="firstName" width="7em" flex-grow="0"></vaadin-grid-column>
          <vaadin-grid-column path="profession" auto-width flex-grow="0"></vaadin-grid-column>
          <vaadin-grid-column path="email"></vaadin-grid-column>
          <vaadin-grid-column
            width="6em"
            flex-grow="0"
            header="Has Sub"
            ${columnBodyRenderer<Person>((item) => html`${item.subscriber ? 'Yes' : 'No'}`, [])}
          ></vaadin-grid-column>
        </vaadin-grid>
        <div></div>
      </vaadin-split-layout>
    `;
  }
}

Sorting

Any column can be used for sorting the data displayed. Enable sorting to allow the user to sort items alphabetically, numerically, by date, or by some other method.

Notice in the example below that each column heading has an up-down arrowhead icon. Click on one of the column headings and notice how the icon is changed to an up arrowhead, and the data in the table resorts alphanumerically in ascending order. Click the same heading again and the arrowhead is flipped and the data resorts in descending order. Do the same for another column.

For detailed information on how to configure sorting in Flow, see the Column Sorting documentation page.

Open in a
new tab

<vaadin-grid .items="${this.items}">
  <vaadin-grid-sort-column path="id"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="displayName" header="Name"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="email"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="profession"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="birthday"></vaadin-grid-sort-column>
</vaadin-grid>

Sorting by Multiple Columns

The Grid can be sorted by multiple columns if multi-sort mode is enabled. When it is enabled, clicking a column header adds that column as a sort criterion instead of replacing the current sort column. A separate multi-sort on shift-click mode combines the two by multi-sorting only when the column header is clicked while holding the Shift key. The order in which multi-sort criteria (i.e., the columns selected) are evaluated is determined by the multi-sort priority setting.

In the example here, click on the Profession column heading to set the first sort criterion. Then click on the Name column heading to set it as the second. Notice that when you select the second column heading, the number 2 is displayed next to it, and 1 next to the first column heading you selected. Notice that the data is sorted first by the profession and then by the full names — not by the last names. As a result, you can see a list of all of the Allergists at the top, sorted by their names. Those results are in ascending order. If you click on the Profession heading again, it sorts the professions in descending order, resulting in Urologists at the top. The names are still in descending order, unless you click that column heading, too.

Open in a
new tab

<vaadin-grid .items="${this.items}" multi-sort multi-sort-priority="append">
  <vaadin-grid-sort-column path="id"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="displayName" header="Name"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="email"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="profession"></vaadin-grid-sort-column>
  <vaadin-grid-sort-column path="birthday"></vaadin-grid-sort-column>
</vaadin-grid>

Note

Shift-Click Multi-Sorting Accessibility Issues

The multi-sort on shift-click mode is not recommended for applications for which accessibility is important. This feature is unlikely to work well with assistive technologies, and the lack of visual affordance makes it difficult to discover for sighted users.

Specifying Sort Property

Columns with rich or custom content can be sorted by defining the property by which to sort. For example, in the table here there’s a column containing the employees' first and last names, avatar images, and email addresses. By clicking on the heading for that column, it’ll sort the data by their last names.

Open in a
new tab

@state()
private accessor items: Person[] = [];

protected override async firstUpdated() {
  const { people } = await getPeople();
  this.items = people;
}

protected override render() {
  return html`
    <vaadin-grid .items="${this.items}">
      <vaadin-grid-sort-column
        header="Employee"
        path="lastName"
        ${columnBodyRenderer(this.employeeRenderer, [])}
      ></vaadin-grid-sort-column>
      <vaadin-grid-column
        ${columnHeaderRenderer(this.birthdayHeaderRenderer, [])}
        ${columnBodyRenderer(this.birthdayRenderer, [])}
      ></vaadin-grid-column>
    </vaadin-grid>
  `;
}

private employeeRenderer: GridColumnBodyLitRenderer<Person> = (person) => html`
  <vaadin-horizontal-layout style="align-items: center;" theme="spacing">
    <vaadin-avatar
      img="${person.pictureUrl}"
      name="${person.firstName} ${person.lastName}"
      alt="User avatar"
    ></vaadin-avatar>
    <vaadin-vertical-layout style="line-height: var(--lumo-line-height-m);">
      <span>${person.firstName} ${person.lastName}</span>
      <span style="font-size: var(--lumo-font-size-s); color: var(--lumo-secondary-text-color);">
        ${person.email}
      </span>
    </vaadin-vertical-layout>
  </vaadin-horizontal-layout>
`;

private birthdayHeaderRenderer = () => html`
  <vaadin-grid-sorter path="birthday">Birthdate</vaadin-grid-sorter>
`;

private birthdayRenderer: GridColumnBodyLitRenderer<Person> = (person) => {
  const birthday = parseISO(person.birthday);
  return html`
    <vaadin-vertical-layout style="line-height: var(--lumo-line-height-m);">
      <span> ${format(birthday, 'P')} </span>
      <span style="font-size: var(--lumo-font-size-s); color: var(--lumo-secondary-text-color);">
        Age: ${differenceInYears(Date.now(), birthday)}
      </span>
    </vaadin-vertical-layout>
  `;
};

Sorting helps users find and examine data. Therefore, it’s recommended to enable sorting for all applicable columns. An exception, though, would be when the order is an essential part of the data itself, such as with prioritized lists.

Filtering

Filtering allows the user to find a specific item or subset of items. You can add filters to Grid columns or use external filter fields.

For instance, try typing anna in the input box for Name below. When you’re finished, the data shown is only people who have anna in their name. That includes some with the names Anna and Annabelle, as well as some with Arianna and Brianna.

Open in a
new tab

<vaadin-grid .items="${this.items}">
  <vaadin-grid-filter-column
    header="Name"
    path="displayName"
    flex-grow="0"
    width="230px"
    ${columnBodyRenderer(this.nameRenderer, [])}
  ></vaadin-grid-filter-column>
  <vaadin-grid-filter-column path="email"></vaadin-grid-filter-column>
  <vaadin-grid-filter-column path="profession"></vaadin-grid-filter-column>
</vaadin-grid>

Place filters outside the grid when the filter is based on multiple columns, or when a bigger field or more complex filter UI is needed, one which wouldn’t fit well in a column. In the example here, whatever you type in the search box can be matched against all of the columns. Type Rheumatologist in the search box. The results show only the rows with that profession.

Open in a
new tab

@state()
private accessor filteredItems: PersonEnhanced[] = [];

private items: PersonEnhanced[] = [];

protected override async firstUpdated() {
  const { people } = await getPeople();
  const items = people.map((person) => ({
    ...person,
    displayName: `${person.firstName} ${person.lastName}`,
  }));
  this.items = items;
  this.filteredItems = items;
}

protected override render() {
  return html`
    <vaadin-vertical-layout theme="spacing">
      <vaadin-text-field
        placeholder="Search"
        style="width: 50%;"
        @value-changed="${(e: TextFieldValueChangedEvent) => {
          const searchTerm = (e.detail.value || '').trim();
          const matchesTerm = (value: string) =>
            value.toLowerCase().includes(searchTerm.toLowerCase());

          this.filteredItems = this.items.filter(
            ({ displayName, email, profession }) =>
              !searchTerm ||
              matchesTerm(displayName) ||
              matchesTerm(email) ||
              matchesTerm(profession)
          );
        }}"
      >
        <vaadin-icon slot="prefix" icon="vaadin:search"></vaadin-icon>
      </vaadin-text-field>
      <vaadin-grid .items="${this.filteredItems}">
        <vaadin-grid-column
          header="Name"
          flex-grow="0"
          width="230px"
          ${columnBodyRenderer(this.nameRenderer, [])}
        ></vaadin-grid-column>
        <vaadin-grid-column path="email"></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
      </vaadin-grid>
    </vaadin-vertical-layout>
  `;
}

Lazy Loading

When you want to display a list of items that would be quite large to load entirely into memory, or you want to load items from a database, data providers can be used to provide lazy loading through pagination.

The following example works like the earlier example, but it uses a data provider for lazy loading, sorting, and filtering items.

Open in a
new tab

async function fetchPeople(params: {
  page: number;
  pageSize: number;
  searchTerm: string;
  sortOrders: GridSorterDefinition[];
}) {
  const { page, pageSize, searchTerm, sortOrders } = params;
  const { people } = await getPeople();

  let result = people.map((person) => ({
    ...person,
    fullName: `${person.firstName} ${person.lastName}`,
  }));

  // Filtering
  if (searchTerm) {
    result = result.filter(
      (p) => matchesTerm(p.fullName, searchTerm) || matchesTerm(p.profession, searchTerm)
    );
  }

  // Sorting
  const sortBy = Object.fromEntries(sortOrders.map(({ path, direction }) => [path, direction]));
  if (sortBy.fullName) {
    result = result.sort((p1, p2) => compare(p1.fullName, p2.fullName, sortBy.fullName));
  } else if (sortBy.profession) {
    result = result.sort((p1, p2) => compare(p1.profession, p2.profession, sortBy.profession));
  }

  // Pagination
  const count = result.length;
  result = result.slice(page * pageSize, pageSize);

  return { people: result, count };
}

...

@state()
private accessor searchTerm = '';

@query('#grid')
private accessor grid!: Grid;

private dataProvider = async (
  params: GridDataProviderParams<Person>,
  callback: GridDataProviderCallback<Person>
) => {
  const { page, pageSize, sortOrders } = params;

  const { people, count } = await fetchPeople({
    page,
    pageSize,
    sortOrders,
    searchTerm: this.searchTerm,
  });

  callback(people, count);
};

protected override render() {
  return html`
    <vaadin-vertical-layout theme="spacing">
      <vaadin-text-field
        placeholder="Search"
        style="width: 50%;"
        @value-changed="${(e: TextFieldValueChangedEvent) => {
          this.searchTerm = (e.detail.value || '').trim();
          this.grid.clearCache();
        }}"
      >
        <vaadin-icon slot="prefix" icon="vaadin:search"></vaadin-icon>
      </vaadin-text-field>
      <vaadin-grid id="grid" .dataProvider="${this.dataProvider}">
        <vaadin-grid-sort-column path="fullName" header="Name"></vaadin-grid-sort-column>
        <vaadin-grid-sort-column path="profession"></vaadin-grid-sort-column>
      </vaadin-grid>
    </vaadin-vertical-layout>
  `;
}

To learn more about data providers, see the Binding Items to Components (Java only) documentation page.

Lazy Column Rendering

Grids containing a large number of columns can sometimes exhibit performance issues. If many of the columns are typically outside the visible viewport, rendering performance can be optimized by using "lazy column rendering" mode.

This mode enables virtual scrolling horizontally. It renders body cells only when their corresponding columns are inside the visible viewport.

Lazy rendering should be used only with a large number of columns and performance is a high priority. For most use cases, though, the default "eager" mode is recommended.

When considering whether to use the "lazy" mode, keep the following factors in mind:

Row Height: When only a number of columns are visible at once, the height of a row can only be that of the highest cell currently visible on that row. Make sure each cell on a single row has the same height as all of the other cells on the row. Otherwise, users may notice jumpiness when horizontally scrolling the grid as lazily rendered cells with different heights are scrolled into view.
Auto-Width Columns: For columns that are initially outside the visible viewport, but still use auto-width, only the header content is taken into account when calculating the column width. This is because the body cells of the columns outside the viewport are not rendered initially.
Screen Reader Compatibility: Screen readers may not be able to associate the focused cells with the correct headers when only a subset of the body cells on a row is rendered.
Keyboard Navigation: Tabbing through focusable elements inside the grid body may not work as expected. This is because some of the columns that would include focusable elements in the body cells may be outside the visible viewport and thus not rendered.
No Improvement If All Columns Visible: The lazy column rendering mode can only improve the rendering performance when a significant portion of the columns are outside of the Grid’s visible viewport. It has no effect on Grids in which all columns are visible without horizontal scrolling.

Open in a
new tab

<vaadin-grid .items="${this.items}" column-rendering="lazy">

Item Details

Item details are expandable content areas that can be displayed below the regular content of a row. They can be used to display more information about an item. By default, an item’s details are toggled by clicking on the item’s row. Try clicking on one of the rows in the example here. Notice that when you do, the row is expanded to show the person’s email address, telephone number, and home address. If you click on the row again, it’s collapsed back to a single line.

Open in a
new tab

@customElement('grid-item-details')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  @state()
  private accessor detailsOpenedItem: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people.map((person) => ({
      ...person,
      displayName: `${person.firstName} ${person.lastName}`,
    }));
  }

  protected override render() {
    return html`
      <vaadin-grid
        theme="row-stripes"
        .items="${this.items}"
        .detailsOpenedItems="${this.detailsOpenedItem}"
        @active-item-changed="${(event: GridActiveItemChangedEvent<Person>) => {
          const person = event.detail.value;
          this.detailsOpenedItem = person ? [person] : [];
        }}"
        ${gridRowDetailsRenderer<Person>(
          (person) => html`
            <vaadin-form-layout .responsiveSteps="${[{ minWidth: '0', columns: 3 }]}">
              <vaadin-text-field
                label="Email address"
                .value="${person.email}"
                colspan="3"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="Phone number"
                .value="${person.address.phone}"
                colspan="3"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="Street address"
                .value="${person.address.street}"
                colspan="3"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="ZIP code"
                .value="${person.address.zip}"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="City"
                .value="${person.address.city}"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="State"
                .value="${person.address.state}"
                readonly
              ></vaadin-text-field>
            </vaadin-form-layout>
          `,
          []
        )}
      >
        <vaadin-grid-column path="displayName" header="Name"></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
      </vaadin-grid>
    `;
  }
}

The default toggle behavior can be replaced by programmatically toggling the details visibility, such as from a button click.

Open in a
new tab

@customElement('grid-item-details-toggle')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  @state()
  private accessor detailsOpenedItems: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people.map((person) => ({
      ...person,
      displayName: `${person.firstName} ${person.lastName}`,
    }));
  }

  protected override render() {
    return html`
      <vaadin-grid
        theme="row-stripes"
        .items="${this.items}"
        .detailsOpenedItems="${this.detailsOpenedItems}"
        ${gridRowDetailsRenderer<Person>(
          (person) => html`
            <vaadin-form-layout .responsiveSteps="${[{ minWidth: '0', columns: 3 }]}">
              <vaadin-text-field
                label="Email address"
                .value="${person.email}"
                colspan="3"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="Phone number"
                .value="${person.address.phone}"
                colspan="3"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="Street address"
                .value="${person.address.street}"
                colspan="3"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="ZIP code"
                .value="${person.address.zip}"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="City"
                .value="${person.address.city}"
                readonly
              ></vaadin-text-field>
              <vaadin-text-field
                label="State"
                .value="${person.address.state}"
                readonly
              ></vaadin-text-field>
            </vaadin-form-layout>
          `,
          []
        )}
      >
        <vaadin-grid-column path="displayName" header="Name"></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
        <vaadin-grid-column
          ${columnBodyRenderer<Person>(
            (person) => html`
              <vaadin-button
                theme="tertiary"
                @click="${() => {
                  const isOpened = this.detailsOpenedItems.includes(person);
                  this.detailsOpenedItems = isOpened
                    ? this.detailsOpenedItems.filter((p) => p !== person)
                    : [...this.detailsOpenedItems, person];
                }}"
              >
                Toggle details
              </vaadin-button>
            `,
            []
          )}
        ></vaadin-grid-column>
      </vaadin-grid>
    `;
  }
}

Tooltips can be used as a lightweight alternative to the item details panel.

You can use Context Menu to provide shortcuts for the user. It appears on a right-click by default. In a mobile browser, a long press opens the menu. In the example here, try right-clicking on one of the rows. You’ll notice a box appears with a list of choices: Edit the row, delete it, email the person, or call them. If this example were fully configured, the latter two would open the related application (i.e., the default email program or a telephone application).

Using a context menu shouldn’t be the only way of accomplishing a task, though. The same functionality needs to be accessible elsewhere in the UI. See the documentation page on Context Menu for more information.

Open in a
new tab

private renderMenu: ContextMenuLitRenderer = (context, menu) => {
  const { sourceEvent } = context.detail as { sourceEvent: Event };
  const grid = menu.firstElementChild as Grid<Person>;

  const eventContext = grid.getEventContext(sourceEvent);
  const person = eventContext.item!;

  const clickHandler = (_action: string) => () => {
    // console.log(`${action}: ${person.firstName} ${person.lastName}`);
  };

  return html`
    <vaadin-list-box>
      <vaadin-item @click="${clickHandler('Edit')}">Edit</vaadin-item>
      <vaadin-item @click="${clickHandler('Delete')}">Delete</vaadin-item>
      <hr />
      <vaadin-item @click="${clickHandler('Email')}">Email (${person.email})</vaadin-item>
      <vaadin-item @click="${clickHandler('Call')}">Call (${person.address.phone})</vaadin-item>
    </vaadin-list-box>
  `;
};

protected override render() {
  return html`
    <vaadin-context-menu ${contextMenuRenderer(this.renderMenu, [])}>
      <vaadin-grid .items="${this.items}" @vaadin-contextmenu="${this.onContextMenu}">
        <vaadin-grid-column path="firstName"></vaadin-grid-column>
        <vaadin-grid-column path="lastName"></vaadin-grid-column>
        <vaadin-grid-column path="email"></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
      </vaadin-grid>
    </vaadin-context-menu>
  `;
}

onContextMenu(e: MouseEvent) {
  // Prevent opening context menu on header row.
  if ((e.currentTarget as Grid).getEventContext(e).section !== 'body') {
    e.stopPropagation();
  }
}

Tooltips

Tooltips on cells can be useful in many situations: They can be used to give more details on the contents of a cell — if an item details panel would be overkill or otherwise undesirable. They can show the full text of a cell if it’s too long to fit feasibly into the cell itself — if wrapping the cell contents is insufficient or otherwise undesirable. Or they can give textual explanations for non-text content, such as status icons.

In the example here, hold your mouse pointer over the birthday date for one of the rows. A tooltip should appear indicating the age of the person. Now hover over one of the status icons, an X or a checkmark. It’ll use Tooltips to interpret the meaning of the icons.

Open in a
new tab

private tooltipGenerator = (context: GridEventContext<Person>): string => {
  let text = '';

  const { column, item } = context;
  if (column && item) {
    switch (column.path) {
      case 'birthday':
        text = `Age: ${differenceInYears(Date.now(), parseISO(item.birthday))}`;
        break;
      case 'status':
        text = item.status;
        break;
      default:
        break;
    }
  }

  return text;
};

...

<vaadin-tooltip slot="tooltip" .generator="${this.tooltipGenerator}"></vaadin-tooltip>

See the Tooltips documentation page for details on tooltip configuration.

Drag & Drop

Grid supports drag-and-drop actions. This feature might be used, for example, to reorder rows and to drag rows between grids.

Drop Mode

The drop mode of a grid determines where a drop can happen. Vaadin offers four different drop modes, which are described in the table here:

Drop Mode

Description

Drops can occur on the grid as a whole, not on top of rows or between individual rows. Use this mode when the order isn’t important.

Drops can happen between rows. Use this mode when the order is important.

Drops can take place on top of rows. This is useful when creating relationships between items or moving an item into another item, such as placing a file inside a folder.

On Top or Between

Drops can occur on top of rows or between them.

Row Reordering

You can drag rows to reorder them. This can be a useful and impressive feature for users. Try dragging with your mouse one of the rows of data in the example here to another place in the list.

Open in a
new tab

@customElement('grid-row-reordering')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: Person[] = [];

  @state()
  private accessor draggedItem: Person | undefined;

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people;
  }

  protected override render() {
    return html`
      <vaadin-grid
        .items="${this.items}"
        rows-draggable
        drop-mode="between"
        @grid-dragstart="${(event: GridDragStartEvent<Person>) => {
          this.draggedItem = event.detail.draggedItems[0];
        }}"
        @grid-dragend="${() => {
          delete this.draggedItem;
        }}"
        @grid-drop="${(event: GridDropEvent<Person>) => {
          const { dropTargetItem, dropLocation } = event.detail;
          // Only act when dropping on another item
          if (this.draggedItem && dropTargetItem !== this.draggedItem) {
            // Remove the item from its previous position
            const draggedItemIndex = this.items.indexOf(this.draggedItem);
            this.items.splice(draggedItemIndex, 1);
            // Re-insert the item at its new position
            const dropIndex =
              this.items.indexOf(dropTargetItem) + (dropLocation === 'below' ? 1 : 0);
            this.items.splice(dropIndex, 0, this.draggedItem);
            // Re-assign the array to refresh the grid
            this.items = [...this.items];
          }
        }}"
      >
        <vaadin-grid-column
          header="Image"
          flex-grow="0"
          auto-width
          ${columnBodyRenderer(this.avatarRenderer, [])}
        ></vaadin-grid-column>
        <vaadin-grid-column path="firstName"></vaadin-grid-column>
        <vaadin-grid-column path="lastName"></vaadin-grid-column>
        <vaadin-grid-column path="email"></vaadin-grid-column>
      </vaadin-grid>
    `;
  }

  private avatarRenderer: GridColumnBodyLitRenderer<Person> = (person) => html`
    <vaadin-avatar
      img="${person.pictureUrl}"
      name="${person.firstName} ${person.lastName}"
      alt="User avatar"
    ></vaadin-avatar>
  `;
}

Drag Rows between Grids

Rows can be dragged from one grid to another. You might use this feature to move, copy or link items from different datasets.

In the example here, there are two grids of data. Maybe they represent people to speak at two different presentations at the same conference. One grid lists the first panel of speakers and the other the second panel. Try dragging people from one to the other, as if you were reassigning them to speak at a different panel.

Open in a
new tab

@state()
private accessor draggedItem: Person | undefined;

@state()
private accessor grid1Items: Person[] = [];

@state()
private accessor grid2Items: Person[] = [];

protected override async firstUpdated() {
  const { people } = await getPeople({ count: 10 });
  this.grid1Items = people.slice(0, 5);
  this.grid2Items = people.slice(5);
}

private startDraggingItem = (event: GridDragStartEvent<Person>) => {
  this.draggedItem = event.detail.draggedItems[0];
};

private clearDraggedItem = () => {
  delete this.draggedItem;
};

protected override render() {
  return html`
    <div class="grids-container">
      <vaadin-grid
        .items="${this.grid1Items}"
        rows-draggable
        drop-mode="on-grid"
        @grid-dragstart="${this.startDraggingItem}"
        @grid-dragend="${this.clearDraggedItem}"
        @grid-drop="${() => {
          const draggedPerson = this.draggedItem!;
          const draggedItemIndex = this.grid2Items.indexOf(draggedPerson);
          if (draggedItemIndex >= 0) {
            // Remove the item from its previous position
            this.grid2Items.splice(draggedItemIndex, 1);
            // Re-assign the array to refresh the grid
            this.grid2Items = [...this.grid2Items];
            // Re-assign the array to refresh the grid
            this.grid1Items = [...this.grid1Items, draggedPerson];
          }
        }}"
      >
        <vaadin-grid-column
          header="Full name"
          ${columnBodyRenderer<Person>(
            (person) => html`${person.firstName} ${person.lastName}`,
            []
          )}
        ></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
      </vaadin-grid>

      <vaadin-grid
        .items="${this.grid2Items}"
        rows-draggable
        drop-mode="on-grid"
        @grid-dragstart="${this.startDraggingItem}"
        @grid-dragend="${this.clearDraggedItem}"
        @grid-drop="${() => {
          const draggedPerson = this.draggedItem!;
          const draggedItemIndex = this.grid1Items.indexOf(draggedPerson);
          if (draggedItemIndex >= 0) {
            // Remove the item from its previous position
            this.grid1Items.splice(draggedItemIndex, 1);
            // Re-assign the array to refresh the grid
            this.grid1Items = [...this.grid1Items];
            // Re-assign the array to refresh the grid
            this.grid2Items = [...this.grid2Items, draggedPerson];
          }
        }}"
      >
        <vaadin-grid-column
          header="Full name"
          ${columnBodyRenderer<Person>(
            (person) => html`${person.firstName} ${person.lastName}`,
            []
          )}
        ></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
      </vaadin-grid>
    </div>
  `;
}

Drag & Drop Filters

Drag-and-drop filters determine which rows are draggable and which rows are valid drop targets. These filters function on a per-row basis.

Open in a
new tab

@customElement('grid-drag-drop-filters')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @query('vaadin-grid')
  private accessor grid!: Grid<Person>;

  @state()
  private accessor draggedItem: Person | undefined;

  @state()
  private accessor items: Person[] = [];

  @state()
  private accessor managers: Person[] = [];

  @state()
  private accessor expandedItems: Person[] = [];

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people;
    this.managers = this.items.filter((item) => item.manager);
    // Avoid using this method
    this.grid.clearCache();
  }

  private dataProvider = (
    params: GridDataProviderParams<Person>,
    callback: GridDataProviderCallback<Person>
  ) => {
    const { page, pageSize, parentItem } = params;
    const startIndex = page * pageSize;
    const endIndex = startIndex + pageSize;

    /*
    We cannot change the underlying data in this demo so this dataProvider uses
    a local field to fetch its values. This allows us to keep a reference to the
    modified list instead of loading a new list every time the dataProvider gets
    called. In a real application, you should always access your data source
    here and avoid using grid.clearCache() whenever possible.
    */
    const result = parentItem
      ? this.items.filter((item) => item.managerId === parentItem.id)
      : this.managers.slice(startIndex, endIndex);

    callback(result, result.length);
  };

  protected override render() {
    return html`
      <vaadin-grid
        .dataProvider="${this.dataProvider}"
        .itemIdPath="${'id'}"
        .itemHasChildrenPath="${'manager'}"
        .expandedItems="${this.expandedItems}"
        @expanded-items-changed="${(event: GridExpandedItemsChangedEvent<Person>) => {
          this.expandedItems = event.detail.value;
        }}"
        rows-draggable
        drop-mode="on-top"
        @grid-dragstart="${(event: GridDragStartEvent<Person>) => {
          this.draggedItem = event.detail.draggedItems[0];
        }}"
        @grid-dragend="${() => {
          delete this.draggedItem;
        }}"
        @grid-drop="${(event: GridDropEvent<Person>) => {
          const manager = event.detail.dropTargetItem;
          if (this.draggedItem) {
            // In a real application, when using a data provider, you should
            // change the persisted data instead of updating a field
            this.draggedItem.managerId = manager.id;
            // Avoid using this method
            this.grid.clearCache();
          }
        }}"
        .dragFilter="${(model: GridItemModel<Person>) => {
          const item = model.item;
          return !item.manager; // Only drag non-managers
        }}"
        .dropFilter="${(model: GridItemModel<Person>) => {
          const item = model.item;
          return (
            item.manager && // Can only drop on a supervisor
            item.id !== this.draggedItem?.managerId // Disallow dropping on the same manager
          );
        }}"
      >
        <vaadin-grid-tree-column path="firstName"></vaadin-grid-tree-column>
        <vaadin-grid-column path="lastName"></vaadin-grid-column>
        <vaadin-grid-column path="email"></vaadin-grid-column>
      </vaadin-grid>
    `;
  }
}

Inline Editing (Java Only)

Grid can be configured to allow inline editing. Editing can be either buffered or non-buffered. Buffered means changes must be explicitly committed, while non-buffered means it automatically commits changes on blur — that is to say, when a field loses focus.

Buffered

To see how buffered inline editing works, click on the Edit button for one of the rows in the example here. The styling for the row changes, the Edit button changes to Save, and a red X appears next to it for canceling any changes. Make a change to some of the data and click Save to see how it works. Next, test the Cancel button — the red X.

Open in a
new tab

Grid<Person> grid = new Grid<>(Person.class, false);
Editor<Person> editor = grid.getEditor();

Grid.Column<Person> firstNameColumn = grid
        .addColumn(Person::getFirstName).setHeader("First name")
        .setWidth("120px").setFlexGrow(0);
Grid.Column<Person> lastNameColumn = grid.addColumn(Person::getLastName)
        .setHeader("Last name").setWidth("120px").setFlexGrow(0);
Grid.Column<Person> emailColumn = grid.addColumn(Person::getEmail)
        .setHeader("Email");
Grid.Column<Person> editColumn = grid.addComponentColumn(person -> {
    Button editButton = new Button("Edit");
    editButton.addClickListener(e -> {
        if (editor.isOpen())
            editor.cancel();
        grid.getEditor().editItem(person);
    });
    return editButton;
}).setWidth("150px").setFlexGrow(0);

Binder<Person> binder = new Binder<>(Person.class);
editor.setBinder(binder);
editor.setBuffered(true);

TextField firstNameField = new TextField();
firstNameField.setWidthFull();
binder.forField(firstNameField)
        .asRequired("First name must not be empty")
        .withStatusLabel(firstNameValidationMessage)
        .bind(Person::getFirstName, Person::setFirstName);
firstNameColumn.setEditorComponent(firstNameField);

TextField lastNameField = new TextField();
lastNameField.setWidthFull();
binder.forField(lastNameField).asRequired("Last name must not be empty")
        .withStatusLabel(lastNameValidationMessage)
        .bind(Person::getLastName, Person::setLastName);
lastNameColumn.setEditorComponent(lastNameField);

EmailField emailField = new EmailField();
emailField.setWidthFull();
binder.forField(emailField).asRequired("Email must not be empty")
        .withValidator(
                new EmailValidator("Enter a valid email address"))
        .withStatusLabel(emailValidationMessage)
        .bind(Person::getEmail, Person::setEmail);
emailColumn.setEditorComponent(emailField);

Button saveButton = new Button("Save", e -> editor.save());
Button cancelButton = new Button(VaadinIcon.CLOSE.create(),
        e -> editor.cancel());
cancelButton.addThemeVariants(ButtonVariant.LUMO_ICON,
        ButtonVariant.LUMO_ERROR);
HorizontalLayout actions = new HorizontalLayout(saveButton,
        cancelButton);
actions.setPadding(false);
editColumn.setEditorComponent(actions);

Non-Buffered

To see how non-buffered works, double-click a row in the example below to start editing it. The styling for the row changes slightly to indicate it’s in edit mode. Press Escape, or click on a different row to stop editing. Notice how the row style returns to its original setting and that changes are saved automatically.

Open in a
new tab

Grid<Person> grid = new Grid<>(Person.class, false);
Grid.Column<Person> firstNameColumn = grid
        .addColumn(Person::getFirstName).setHeader("First name")
        .setWidth("120px").setFlexGrow(0);
Grid.Column<Person> lastNameColumn = grid.addColumn(Person::getLastName)
        .setHeader("Last name").setWidth("120px").setFlexGrow(0);
Grid.Column<Person> emailColumn = grid.addColumn(Person::getEmail)
        .setHeader("Email");

Binder<Person> binder = new Binder<>(Person.class);
Editor<Person> editor = grid.getEditor();
editor.setBinder(binder);

TextField firstNameField = new TextField();
firstNameField.setWidthFull();
addCloseHandler(firstNameField, editor);
binder.forField(firstNameField)
        .asRequired("First name must not be empty")
        .withStatusLabel(firstNameValidationMessage)
        .bind(Person::getFirstName, Person::setFirstName);
firstNameColumn.setEditorComponent(firstNameField);

TextField lastNameField = new TextField();
lastNameField.setWidthFull();
addCloseHandler(lastNameField, editor);
binder.forField(lastNameField).asRequired("Last name must not be empty")
        .withStatusLabel(lastNameValidationMessage)
        .bind(Person::getLastName, Person::setLastName);
lastNameColumn.setEditorComponent(lastNameField);

EmailField emailField = new EmailField();
emailField.setWidthFull();
addCloseHandler(emailField, editor);
binder.forField(emailField).asRequired("Email must not be empty")
        .withValidator(
                new EmailValidator("Enter a valid email address"))
        .withStatusLabel(emailValidationMessage)
        .bind(Person::getEmail, Person::setEmail);
emailColumn.setEditorComponent(emailField);

grid.addItemDoubleClickListener(e -> {
    editor.editItem(e.getItem());
    Component editorComponent = e.getColumn().getEditorComponent();
    if (editorComponent instanceof Focusable) {
        ((Focusable) editorComponent).focus();
    }
});

As an alternative, use Grid Pro for more streamlined inline editing, or CRUD for editing in a separate side panel or dialog.

Styling Rows & Columns Dynamically

Cells can be styled dynamically, based on application logic and the data in the grid, through custom part names. This can be used, for example, to highlight specific rows and apply custom styling to specific columns.

In the example below, bold font weight is applied to the Rating column with a font-weight-bold part name, and the rows are colored red and green, based on their rating, with low-rating and high-rating part names, respectively. The styling itself is applied in a stylesheet with vaadin-grid::part() selectors (e.g., vaadin-grid::part(high-rating)).

Open in a
new tab

interface PersonWithRating extends Person {
  customerRating: number;
}

@customElement('grid-styling')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: PersonWithRating[] = [];

  private ratingFormatter = new Intl.NumberFormat('en-US', {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people.map((person) => ({ ...person, customerRating: Math.random() * 10 }));
  }

  protected override render() {
    return html`
      <vaadin-grid
        .items="${this.items}"
        .cellPartNameGenerator="${this.cellPartNameGenerator}"
        class="styling"
      >
        <vaadin-grid-column path="firstName"></vaadin-grid-column>
        <vaadin-grid-column path="lastName"></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
        <vaadin-grid-column
          header="Customer rating (0-10)"
          ${columnBodyRenderer(this.ratingRenderer, [])}
        ></vaadin-grid-column>
      </vaadin-grid>
    `;
  }

  private ratingRenderer: GridColumnBodyLitRenderer<PersonWithRating> = (person) => html`
    <span>${this.ratingFormatter.format(person.customerRating)}</span>
  `;

  private cellPartNameGenerator(column: GridColumn, model: GridItemModel<PersonWithRating>) {
    const item = model.item;
    let parts = '';
    // Make the customer rating column bold
    if (column.header?.startsWith('Customer rating')) {
      parts += ' font-weight-bold';
    }
    // Add high-rating part to customer ratings of 8 or higher
    if (item.customerRating >= 8.0) {
      parts += ' high-rating';
      // Add low-rating part to customer ratings of 4 or lower
    } else if (item.customerRating <= 4.0) {
      parts += ' low-rating';
    }
    return parts;
  }
}

Styling Header & Footer Cells

Header and footer cells can be similarly styled through their own custom part names.

Open in a
new tab

interface PersonWithRating extends Person {
  customerRating: number;
}

@customElement('grid-header-footer-styling')
export class Example extends LitElement {
  protected override createRenderRoot() {
    const root = super.createRenderRoot();
    // Apply custom theme (only supported if your app uses one)
    applyTheme(root);
    return root;
  }

  @state()
  private accessor items: PersonWithRating[] = [];

  private ratingFormatter = new Intl.NumberFormat('en-US', {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2,
  });

  protected override async firstUpdated() {
    const { people } = await getPeople();
    this.items = people.map((person) => ({ ...person, customerRating: Math.random() * 10 }));
  }

  protected override render() {
    return html`
      <vaadin-grid .items="${this.items}" class="styling-header-footer">
        <vaadin-grid-column path="firstName"></vaadin-grid-column>
        <vaadin-grid-column path="lastName"></vaadin-grid-column>
        <vaadin-grid-column path="profession"></vaadin-grid-column>
        <vaadin-grid-column
          header="Customer rating (0-10)"
          header-part-name="rating-header"
          footer-part-name="rating-footer"
          ${columnFooterRenderer(() => html`<span>Avg rating: 5.32</span>`, [])}
          ${columnBodyRenderer(this.ratingRenderer, [])}
        ></vaadin-grid-column>
      </vaadin-grid>
    `;
  }

  private ratingRenderer: GridColumnBodyLitRenderer<PersonWithRating> = (person) => html`
    <span>${this.ratingFormatter.format(person.customerRating)}</span>
  `;
}

Theme Variants

Grid variants can reduce the white space inside the grid, adjust the border and row to highlight visibility, and control cell content overflow behavior. They’re versatile and can be combined.

Compact

The compact theme variant makes a grid denser by reducing the header and row heights, as well as the spacing between columns.

This is useful for displaying more information on-screen without having to scroll. It can also help improve scannability and comparability between rows. Notice that there are more rows displayed in the example here, compared to the number of rows visible in the same space in the earlier example.

Open in a
new tab

<vaadin-grid .items="${this.items}" theme="compact">
  <vaadin-grid-column path="firstName"></vaadin-grid-column>
  <vaadin-grid-column path="lastName"></vaadin-grid-column>
  <vaadin-grid-column path="email"></vaadin-grid-column>
</vaadin-grid>

No Border

The no-border theme variant removes the outer border of the grid. Compare the example here with the previous one. Notice that the outer border, surrounding all of the rows is missing here.

Open in a
new tab

<vaadin-grid .items="${this.items}" theme="no-border">
  <vaadin-grid-column
    header="Image"
    flex-grow="0"
    auto-width
    ${columnBodyRenderer(this.avatarRenderer, [])}
  ></vaadin-grid-column>
  <vaadin-grid-column path="firstName"></vaadin-grid-column>
  <vaadin-grid-column path="lastName"></vaadin-grid-column>
  <vaadin-grid-column path="email"></vaadin-grid-column>
</vaadin-grid>

No Row Border

This theme variant removes the horizontal row borders. This is best suited for small datasets. Viewing larger datasets may be difficult unless paired with the row-stripes theme variant. You can see this in the example here. There’s no border between the rows. With so much space, notice how it’s a little difficult to be sure you’re reading the email address of a particular person — and not the email address of a different row. It would be worse with a wider table containing many columns of data.

Open in a
new tab

<vaadin-grid .items="${this.items}" theme="no-row-borders">
  <vaadin-grid-column
    header="Image"
    flex-grow="0"
    auto-width
    ${columnBodyRenderer(this.avatarRenderer, [])}
  ></vaadin-grid-column>
  <vaadin-grid-column path="firstName"></vaadin-grid-column>
  <vaadin-grid-column path="lastName"></vaadin-grid-column>
  <vaadin-grid-column path="email"></vaadin-grid-column>
</vaadin-grid>

Column Borders

You can add vertical borders between columns by using the column-borders theme variant. Datasets with a lot of cramped columns, or where content is truncated, can benefit from the extra separation that vertical borders bring. Compare the table here to previous ones. You can see that this one has a border between each column. While this can sometimes make reading the data easier, it can be aesthetically displeasing — look too rigid.

Open in a
new tab

<vaadin-grid .items="${this.items}" theme="column-borders">
  <vaadin-grid-column
    header="Image"
    flex-grow="0"
    auto-width
    ${columnBodyRenderer(this.avatarRenderer, [])}
  ></vaadin-grid-column>
  <vaadin-grid-column path="firstName"></vaadin-grid-column>
  <vaadin-grid-column path="lastName"></vaadin-grid-column>
  <vaadin-grid-column path="email"></vaadin-grid-column>
</vaadin-grid>

Row Stripes

The row-stripes theme variant produces a background color for every other row. This can make scanning the rows of data easier. You can see in the example here that the odd rows have a light gray background, while the even ones have none or a white background. This is particularly useful with very wide tables, with many columns of data.

Open in a
new tab

<vaadin-grid .items="${this.items}" theme="row-stripes">
  <vaadin-grid-column
    header="Image"
    flex-grow="0"
    auto-width
    ${columnBodyRenderer(this.avatarRenderer, [])}
  ></vaadin-grid-column>
  <vaadin-grid-column path="firstName"></vaadin-grid-column>
  <vaadin-grid-column path="lastName"></vaadin-grid-column>
  <vaadin-grid-column path="email"></vaadin-grid-column>
</vaadin-grid>

Cell Focus

Many of the explanations and examples above alluded to giving the focus to rows and cells. Cells can be focused by clicking on a cell, or with the keyboard. The following keyboard shortcuts are available with Grid:

Keys

Action

Tab

Switches focus between sections of the grid (i.e., header, body, footer).

Left, Up, Right, and Down Arrow Keys

Moves focus between cells within a section of the grid.

Page Up

Moves cell focus up by one page of visible rows.

Page Down

Moves cell focus down by one page of visible rows.

Home

Moves focus to the first cell in a row.

End

Moves focus to the last cell in a row.

The cell focus event can be used to be notified when the user changes focus between cells. By default, the focus outline is only visible when using keyboard navigation. For illustrative purposes, the example below also uses custom styles to show the focus outline when clicking on cells. Try clicking on a cell. Notice how the cell is highlighted and notice the information shown at the bottom, the information provided about the event.

Open in a
new tab

protected override render() {
  return html`
    <vaadin-grid
      class="force-focus-outline"
      .items="${this.items}"
      @cell-focus="${(e: GridCellFocusEvent<Person>) => {
        const eventContext = this.grid.getEventContext(e);
        const section = eventContext.section ?? 'Not available';
        const row = eventContext.index != null ? eventContext.index : 'Not available';
        const column = eventContext.column?.path ?? 'Not available';
        const person = eventContext.item;
        const fullName =
          person?.firstName && person?.lastName
            ? `${person.firstName} ${person.lastName}`
            : 'Not available';

        this.eventSummary = `Section: ${section}\nRow: ${row}\nColumn: ${column}\nPerson: ${fullName}`;
      }}"
    >
      <vaadin-grid-column path="firstName"></vaadin-grid-column>
      <vaadin-grid-column path="lastName"></vaadin-grid-column>
      <vaadin-grid-column path="email"></vaadin-grid-column>
      <vaadin-grid-column path="profession"></vaadin-grid-column>
    </vaadin-grid>
    <div>
      <vaadin-text-area
        label="Cell focus event information"
        readonly
        .value="${this.eventSummary}"
      ></vaadin-text-area>
    </div>
  `;
}

Component

Usage Recommendation

Component for creating, displaying, updating, and deleting tabular data.

Component for showing and editing tabular data.

Component for showing hierarchical tabular data.

Lightweight component for lightweight, single-column lists.

AC63AABF-4102-4C3E-9776-A09DDC04EF37