Context Menu

Dividers
Checkable Menu Items
Hierarchical Menu
Custom Items
Disabled Menu Items
Left-Click
Best Practices
Related Components

Context Menu is a component that you can attach to any component to display a context menu. The menu appears on right (default) or left click. On a touch device, a long press opens the context menu.

Important

Open the Context Menu by right-clicking (mouse) or long-pressing (touch) a Grid row.

Open in a
new tab

Source code

context-menu-basic.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/context-menu';
import '@vaadin/grid';
import type { Grid } from '@vaadin/grid';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('context-menu-basic')
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;
  }

  // tag::snippet[]
  @state()
  private items = [{ text: 'View' }, { text: 'Edit' }, { text: 'Delete' }];
  // end::snippet[]

  @state()
  private gridItems: Person[] = [];

  protected override async firstUpdated() {
    this.gridItems = (await getPeople({ count: 5 })).people;
  }

  protected override render() {
    return html`
      <!-- tag::snippethtml[] -->
      <vaadin-context-menu .items=${this.items}>
        <vaadin-grid
          all-rows-visible
          .items=${this.gridItems}
          @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 header="Phone number" path="address.phone"></vaadin-grid-column>
        </vaadin-grid>
      </vaadin-context-menu>
      <!-- end::snippethtml[] -->
    `;
  }

  onContextMenu(e: MouseEvent) {
    // Prevent opening context menu on header row.
    const target = e.currentTarget as Grid<Person>;
    if (target.getEventContext(e).section !== 'body') {
      e.stopPropagation();
    }
  }
}
ContextMenuBasic.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.grid.contextmenu.GridContextMenu;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

import java.util.List;

@Route("context-menu-basic")
public class ContextMenuBasic extends Div {

    private List<Person> people = DataService.getPeople(5);

    public ContextMenuBasic() {
        Grid<Person> grid = new Grid();
        grid.setAllRowsVisible(true);
        grid.setItems(people);

        grid.addColumn(person -> person.getFirstName()).setHeader("First name");
        grid.addColumn(person -> person.getLastName()).setHeader("Last name");
        grid.addColumn(person -> person.getEmail()).setHeader("Email");
        grid.addColumn(person -> person.getAddress().getPhone())
                .setHeader("Phone number");

        // tag::snippet[]
        GridContextMenu<Person> menu = grid.addContextMenu();
        menu.addItem("View", event -> {
        });
        menu.addItem("Edit", event -> {
        });
        menu.addItem("Delete", event -> {
        });
        // end::snippet[]

        add(grid);
    }

}

Dividers

You can use dividers to separate and group related content. Use dividers sparingly to avoid creating unnecessary visual clutter.

Important

Open the Context Menu by right-clicking (mouse) or long-pressing (touch) a Grid row.

Open in a
new tab

Source code

context-menu-dividers.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/context-menu';
import '@vaadin/grid';
import type { Grid } from '@vaadin/grid';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('context-menu-dividers')
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 gridItems: Person[] = [];

  protected override async firstUpdated() {
    this.gridItems = (await getPeople({ count: 5 })).people;
  }

  protected override render() {
    return html`
      <!-- tag::snippet[] -->
      <vaadin-context-menu
        .items=${[
          { text: 'View' },
          { component: 'hr' },
          { text: 'Edit' },
          { text: 'Delete' },
          { component: 'hr' },
          { text: 'Email' },
          { text: 'Call' },
        ]}
      >
        <vaadin-grid
          all-rows-visible
          .items=${this.gridItems}
          @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 header="Phone number" path="address.phone"></vaadin-grid-column>
        </vaadin-grid>
      </vaadin-context-menu>
      <!-- end::snippet[] -->
    `;
  }

  onContextMenu(e: MouseEvent) {
    // Prevent opening context menu on header row.
    const target = e.currentTarget as Grid<Person>;
    if (target.getEventContext(e).section !== 'body') {
      e.stopPropagation();
    }
  }
}
ContextMenuDividers.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.grid.contextmenu.GridContextMenu;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Hr;
import com.vaadin.flow.router.Route;

import java.util.List;

@Route("context-menu-dividers")
public class ContextMenuDividers extends Div {

    private List<Person> people = DataService.getPeople(5);

    public ContextMenuDividers() {
        Grid<Person> grid = new Grid();
        grid.setAllRowsVisible(true);
        grid.setItems(people);

        grid.addColumn(person -> person.getFirstName()).setHeader("First name");
        grid.addColumn(person -> person.getLastName()).setHeader("Last name");
        grid.addColumn(person -> person.getEmail()).setHeader("Email");
        grid.addColumn(person -> person.getAddress().getPhone())
                .setHeader("Phone number");

        // tag::snippet[]
        GridContextMenu<Person> menu = grid.addContextMenu();
        menu.addItem("View", event -> {
        });
        menu.add(new Hr());
        menu.addItem("Edit", event -> {
        });
        menu.addItem("Delete", event -> {
        });
        menu.add(new Hr());
        menu.addItem("Email", event -> {
        });
        menu.addItem("Call", event -> {
        });
        // end::snippet[]

        add(grid);
    }

}

Checkable Menu Items can be used to toggle a setting on and off.

Open in a
new tab

Source code

context-menu-checkable.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/context-menu';
import type { ContextMenuItem, ContextMenuItemSelectedEvent } from '@vaadin/context-menu';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('context-menu-checkable')
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;
  }

  // tag::snippet[]
  @state()
  private items: ContextMenuItem[] = [
    { text: 'Abigail Lewis', checked: true },
    { text: 'Allison Torres' },
    { text: 'Anna Myers' },
    { text: 'Lauren Wright' },
    { text: 'Tamaki Ryushi' },
  ];

  protected override render() {
    const selectedItem = this.items.find((item) => item.checked);

    return html`
      <vaadin-context-menu .items="${this.items}" @item-selected="${this.itemSelected}">
        <span>Assignee: <b>${selectedItem?.text}</b></span>
      </vaadin-context-menu>
    `;
  }

  itemSelected(e: ContextMenuItemSelectedEvent) {
    this.items.forEach((item) => {
      item.checked = item === e.detail.value;
    });
    this.items = [...this.items];
  }
  // end::snippet[]
}
ContextMenuCheckable.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.contextmenu.ContextMenu;
import com.vaadin.flow.component.contextmenu.MenuItem;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Span;
import com.vaadin.flow.router.Route;

import java.util.List;

@Route("context-menu-checkable")
public class ContextMenuCheckable extends Div {

    private final ContextMenu menu;
    private final Span assignee;

    public ContextMenuCheckable() {
        // tag::snippet1[]
        assignee = new Span();
        menu = new ContextMenu();
        menu.setTarget(assignee);

        List<Person> people = DataService.getPeople(5);
        for (Person person : people) {
            MenuItem menuItem = menu.addItem(person.getFullName(), event -> {
                setAssignee(person);
            });
            menuItem.setCheckable(true);
        }

        setAssignee(people.get(0));
        // end::snippet1[]

        Div assigneeInfo = new Div(new Span("Assignee: "), assignee);
        assignee.getStyle().set("font-weight", "bold");

        add(assigneeInfo);
    }

    private void setAssignee(Person person) {
        // Update checked state of menu items
        menu.getItems().forEach(item -> item
                .setChecked(item.getText().equals(person.getFullName())));

        assignee.setText(person.getFullName());
    }

}

Context Menu, like Menu Bar, supports multi-level sub-menus. You can use a hierarchical menu to organize a large set of options and group related items.

Important

Open the Context Menu by right-clicking (mouse) or long-pressing (touch) a Grid row.

Open in a
new tab

Source code

context-menu-hierarchical.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/context-menu';
import '@vaadin/grid';
import type { Grid } from '@vaadin/grid';
import { applyTheme } from 'Frontend/generated/theme';

interface FileItem {
  name: string;
  size: string;
}

@customElement('context-menu-hierarchical')
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;
  }

  // tag::snippet[]
  @state()
  private items = [
    { text: 'Preview' },
    { text: 'Edit' },
    { component: 'hr' },
    {
      text: 'Export',
      children: [
        { text: 'Portable Document Format (.pdf)' },
        { text: 'Rich Text Format (.rtf)' },
        { text: 'Plain text (.txt)' },
      ],
    },
    { text: 'Share', children: [{ text: 'Copy link' }, { text: 'Email' }] },
    { component: 'hr' },
    { text: 'Delete' },
  ];
  // end::snippet[]

  @state()
  private gridItems: FileItem[] = [
    { name: 'Annual Report.docx', size: '24 MB' },
    { name: 'Financials.xlsx', size: '42 MB' },
  ];

  protected override render() {
    return html`
      <!-- tag::snippethtml[] -->
      <vaadin-context-menu .items=${this.items}>
        <vaadin-grid
          all-rows-visible
          .items=${this.gridItems}
          @vaadin-contextmenu=${this.onContextMenu}
        >
          <vaadin-grid-column path="name"></vaadin-grid-column>
          <vaadin-grid-column path="size"></vaadin-grid-column>
        </vaadin-grid>
      </vaadin-context-menu>
      <!-- end::snippethtml[] -->
    `;
  }

  onContextMenu(e: MouseEvent) {
    // Prevent opening context menu on header row.
    const target = e.currentTarget as Grid<FileItem>;
    if (target.getEventContext(e).section !== 'body') {
      e.stopPropagation();
    }
  }
}
ContextMenuHierarchical.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.grid.contextmenu.GridContextMenu;
import com.vaadin.flow.component.grid.contextmenu.GridMenuItem;
import com.vaadin.flow.component.grid.contextmenu.GridSubMenu;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Hr;
import com.vaadin.flow.router.Route;

import static org.apache.commons.io.FileUtils.byteCountToDisplaySize;

@Route("context-menu-hierarchical")
public class ContextMenuHierarchical extends Div {

    public ContextMenuHierarchical() {
        Grid<File> grid = new Grid();
        grid.setAllRowsVisible(true);
        grid.setItems(getFiles());

        grid.addColumn(File::getName).setHeader("Name");
        grid.addColumn(File::getDisplaySize).setHeader("Size");

        // tag::snippet[]
        GridContextMenu<File> menu = grid.addContextMenu();
        // end::snippet[]
        menu.addItem("Preview", event -> {
        });
        menu.addItem("Edit", event -> {
        });
        menu.add(new Hr());

        // tag::snippet[]
        GridMenuItem<File> export = menu.addItem("Export");
        GridSubMenu<File> exportSubMenu = export.getSubMenu();
        exportSubMenu.addItem("Portable Document Format (.pdf)", event -> {
        });
        exportSubMenu.addItem("Rich Text Format (.rtf)", event -> {
        });
        exportSubMenu.addItem("Plain text (.txt)", event -> {
        });
        // end::snippet[]

        GridMenuItem<File> share = menu.addItem("Share");
        GridSubMenu<File> shareSubMenu = share.getSubMenu();
        shareSubMenu.addItem("Copy link", event -> {
        });
        shareSubMenu.addItem("Email", event -> {
        });
        menu.add(new Hr());

        menu.addItem("Delete", event -> {
        });

        add(grid);
    }

    private File[] getFiles() {
        return new File[] { new File("Annual Report.docx", 25165824),
                new File("Financials.xlsx", 44040192) };
    }

    private class File {

        private String name;
        private long size;

        File(String name, long size) {
            this.name = name;
            this.size = size;
        }

        public String getName() {
            return name;
        }

        public long getSize() {
            return size;
        }

        public String getDisplaySize() {
            return byteCountToDisplaySize(size);
        }
    }

}

Custom Items

You can customize the items to include more than a single line of text.

Important

Open the Context Menu by right-clicking (mouse) or long-pressing (touch) a Grid row.

Open in a
new tab

Source code

context-menu-presentation.tsimport { html, LitElement, render } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/avatar';
import '@vaadin/context-menu';
import type { ContextMenuItem } from '@vaadin/context-menu';
import '@vaadin/grid';
import { columnBodyRenderer } from '@vaadin/grid/lit.js';
import type { Grid } from '@vaadin/grid';
import '@vaadin/icon';
import '@vaadin/icons';
import '@vaadin/horizontal-layout';
import '@vaadin/vertical-layout';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('context-menu-presentation')
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 gridItems: Person[] = [];

  @state()
  private items?: ContextMenuItem[];

  // tag::snippet[]
  protected override async firstUpdated() {
    const { people } = await getPeople({ count: 10 });

    this.gridItems = people.slice(0, 5);
    const itemsArray = this.createItemsArray(people.slice(5, 10));

    this.items = [
      { component: this.createItem('vaadin:file-search', 'Open') },
      {
        component: this.createItem('vaadin:user-check', 'Assign'),
        children: [
          { component: itemsArray[0] },
          { component: itemsArray[1] },
          { component: itemsArray[2] },
          { component: itemsArray[3] },
          { component: itemsArray[4] },
        ],
      },
      { component: 'hr' },
      { component: this.createItem('vaadin:trash', 'Delete') },
    ];
  }
  // end::snippet[]

  protected override render() {
    return html`
      <!-- tag::snippethtml[] -->
      <vaadin-context-menu .items=${this.items}>
        <vaadin-grid
          all-rows-visible
          .items=${this.gridItems}
          @vaadin-contextmenu=${this.onContextMenu}
        >
          <vaadin-grid-column
            header="Applicant"
            ${columnBodyRenderer<Person>(
              (person) => html`<span>${person.firstName} ${person.lastName}</span>`,
              []
            )}
          ></vaadin-grid-column>
          <vaadin-grid-column path="email"></vaadin-grid-column>
          <vaadin-grid-column header="Phone number" path="address.phone"></vaadin-grid-column>
        </vaadin-grid>
      </vaadin-context-menu>
      <!-- end::snippethtml[] -->
    `;
  }

  createItemsArray(people: Person[]) {
    return people.map((person, index) => {
      const item = document.createElement('vaadin-item');
      if (index === 0) {
        item.setAttribute('selected', '');
      }
      render(
        html`
          <vaadin-horizontal-layout
            style="align-items: center; line-height: var(--lumo-line-height-m)"
            theme="spacing"
          >
            <vaadin-avatar
              .img=${person.pictureUrl}
              .name=${`${person.firstName} ${person.lastName}`}
            ></vaadin-avatar>
            <vaadin-vertical-layout>
              <span> ${person.firstName} ${person.lastName} </span>
              <span
                style="color: var(--lumo-secondary-text-color); font-size: var(--lumo-font-size-s);"
              >
                ${Math.floor(Math.random() * 20) + 1} applications
              </span>
            </vaadin-vertical-layout>
          </vaadin-horizontal-layout>
        `,
        item
      );
      return item;
    });
  }

  createItem(iconName: string, text: string) {
    const item = document.createElement('vaadin-context-menu-item');
    const icon = document.createElement('vaadin-icon');

    icon.style.color = 'var(--lumo-secondary-text-color)';
    icon.style.marginInlineEnd = 'var(--lumo-space-s)';
    icon.style.padding = 'var(--lumo-space-xs)';

    icon.setAttribute('icon', iconName);
    item.appendChild(icon);
    if (text) {
      item.appendChild(document.createTextNode(text));
    }
    return item;
  }

  onContextMenu(e: MouseEvent) {
    // Prevent opening context menu on header row.
    const target = e.currentTarget as Grid<Person>;
    if (target.getEventContext(e).section !== 'body') {
      e.stopPropagation();
    }
  }
}
ContextMenuPresentation.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.Component;
import com.vaadin.flow.component.avatar.Avatar;
import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.grid.contextmenu.GridContextMenu;
import com.vaadin.flow.component.grid.contextmenu.GridMenuItem;
import com.vaadin.flow.component.grid.contextmenu.GridSubMenu;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Hr;
import com.vaadin.flow.component.html.Span;
import com.vaadin.flow.component.icon.Icon;
import com.vaadin.flow.component.icon.VaadinIcon;
import com.vaadin.flow.component.orderedlayout.FlexComponent;
import com.vaadin.flow.component.orderedlayout.HorizontalLayout;
import com.vaadin.flow.component.orderedlayout.VerticalLayout;
import com.vaadin.flow.router.Route;

import java.util.List;
import java.util.Random;

@Route("context-menu-presentation")
public class ContextMenuPresentation extends Div {

    private List<Person> people = DataService.getPeople(10);
    private Random random = new Random(1);

    public ContextMenuPresentation() {
        Grid<Person> grid = new Grid();
        grid.setAllRowsVisible(true);
        grid.setItems(people.subList(0, 5));

        grid.addColumn(person -> person.getFullName()).setHeader("Applicant");
        grid.addColumn(person -> person.getEmail()).setHeader("Email");
        grid.addColumn(person -> person.getAddress().getPhone())
                .setHeader("Phone number");

        // tag::snippet1[]
        GridContextMenu<Person> menu = grid.addContextMenu();
        // end::snippet1[]

        GridMenuItem<Person> open = menu.addItem("Open", event -> {
        });
        open.addComponentAsFirst(createIcon(VaadinIcon.FILE_SEARCH));

        GridMenuItem<Person> assign = menu.addItem("Assign");
        assign.addComponentAsFirst(createIcon(VaadinIcon.USER_CHECK));

        GridSubMenu<Person> assignSubMenu = assign.getSubMenu();
        people.subList(5, 10).forEach(person -> {
            assignSubMenu.addItem(createPersonItem(person), event -> {
            });
        });
        menu.add(new Hr());

        GridMenuItem<Person> delete = menu.addItem("Delete", event -> {
        });
        delete.addComponentAsFirst(createIcon(VaadinIcon.TRASH));

        add(grid);
    }

    private Component createIcon(VaadinIcon vaadinIcon) {
        Icon icon = vaadinIcon.create();
        icon.getStyle().set("color", "var(--lumo-secondary-text-color)")
                .set("margin-inline-end", "var(--lumo-space-s")
                .set("padding", "var(--lumo-space-xs");
        return icon;
    }

    private Component createPersonItem(Person person) {
        Avatar avatar = new Avatar();
        avatar.setImage(person.getPictureUrl());
        avatar.setName(person.getFirstName());

        Span name = new Span(person.getFullName());
        Span apps = new Span(getApplicationCount());
        apps.getStyle().set("color", "var(--lumo-secondary-text-color)")
                .set("font-size", "var(--lumo-font-size-s)");

        VerticalLayout verticalLayout = new VerticalLayout(name, apps);
        verticalLayout.setPadding(false);
        verticalLayout.setSpacing(false);

        HorizontalLayout horizontalLayout = new HorizontalLayout(avatar,
                verticalLayout);
        horizontalLayout.setAlignItems(FlexComponent.Alignment.CENTER);
        horizontalLayout.getStyle().set("line-height",
                "var(--lumo-line-height-m)");
        return horizontalLayout;
    }

    private String getApplicationCount() {
        // Randomised dummy data
        return random.nextInt(20) + 1 + " applications";
    }

}

You can disable menu items to show that they are unavailable.

Important

Open the Context Menu by right-clicking (mouse) or long-pressing (touch) a Grid row.

Open in a
new tab

Source code

context-menu-disabled.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/context-menu';
import '@vaadin/grid';
import type { Grid } from '@vaadin/grid';
import { applyTheme } from 'Frontend/generated/theme';

interface FileItem {
  name: string;
  size: string;
}

@customElement('context-menu-disabled')
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;
  }

  // tag::snippet[]
  @state()
  private items = [
    { text: 'Preview' },
    { text: 'Edit' },
    { component: 'hr' },
    {
      text: 'Export',
      children: [
        { text: 'Portable Document Format (.pdf)', disabled: true },
        { text: 'Rich Text Format (.rtf)' },
        { text: 'Plain text (.txt)' },
      ],
    },
    { text: 'Share', children: [{ text: 'Copy link' }, { text: 'Email' }] },
    { component: 'hr' },
    { text: 'Delete', disabled: true },
  ];
  // end::snippet[]

  @state()
  private gridItems: FileItem[] = [
    { name: 'Annual Report.pdf', size: '24 MB' },
    { name: 'Financials.pdf', size: '42 MB' },
  ];

  protected override render() {
    return html`
      <!-- tag::snippethtml[] -->
      <vaadin-context-menu .items=${this.items}>
        <vaadin-grid
          all-rows-visible
          .items=${this.gridItems}
          @vaadin-contextmenu=${this.onContextMenu}
        >
          <vaadin-grid-column path="name"></vaadin-grid-column>
          <vaadin-grid-column path="size"></vaadin-grid-column>
        </vaadin-grid>
      </vaadin-context-menu>
      <!-- end::snippethtml[] -->
    `;
  }

  onContextMenu(e: MouseEvent) {
    // Prevent opening context menu on header row.
    const target = e.currentTarget as Grid<FileItem>;
    if (target.getEventContext(e).section !== 'body') {
      e.stopPropagation();
    }
  }
}
ContextMenuDisabled.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.grid.contextmenu.GridContextMenu;
import com.vaadin.flow.component.grid.contextmenu.GridMenuItem;
import com.vaadin.flow.component.grid.contextmenu.GridSubMenu;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.html.Hr;
import com.vaadin.flow.router.Route;

import static org.apache.commons.io.FileUtils.byteCountToDisplaySize;

@Route("context-menu-disabled")
public class ContextMenuDisabled extends Div {

    public ContextMenuDisabled() {
        Grid<File> grid = new Grid();
        grid.setAllRowsVisible(true);
        grid.setItems(getFiles());

        grid.addColumn(File::getName).setHeader("Name");
        grid.addColumn(File::getDisplaySize).setHeader("Size");

        // tag::snippet1[]
        GridContextMenu<File> menu = grid.addContextMenu();
        // end::snippet1[]
        menu.addItem("Preview", event -> {
        });
        menu.addItem("Edit", event -> {
        });
        menu.add(new Hr());

        GridMenuItem<File> export = menu.addItem("Export");
        GridSubMenu<File> exportSubMenu = export.getSubMenu();
        GridMenuItem<File> exportPDF = exportSubMenu
                .addItem("Portable Document Format (.pdf)", event -> {
                });
        exportPDF.setEnabled(false);
        exportSubMenu.addItem("Rich Text Format (.rtf)", event -> {
        });
        exportSubMenu.addItem("Plain text (.txt)", event -> {
        });

        GridMenuItem<File> share = menu.addItem("Share");
        GridSubMenu<File> shareSubMenu = share.getSubMenu();
        shareSubMenu.addItem("Copy link", event -> {
        });
        shareSubMenu.addItem("Email", event -> {
        });
        menu.add(new Hr());

        GridMenuItem<File> delete = menu.addItem("Delete", event -> {
        });
        delete.setEnabled(false);

        add(grid);
    }

    private File[] getFiles() {
        return new File[] { new File("Annual Report.pdf", 25165824),
                new File("Financials.pdf", 44040192) };
    }

    private class File {

        private String name;
        private long size;

        File(String name, long size) {
            this.name = name;
            this.size = size;
        }

        public String getName() {
            return name;
        }

        public long getSize() {
            return size;
        }

        public String getDisplaySize() {
            return byteCountToDisplaySize(size);
        }
    }

}

Left-Click

You can use left-click to open Context Menu in situations where left-click doesn’t have any other function, for example a Grid without selection support.

Important

Open the Context Menu by clicking a Grid row.

Open in a
new tab

Source code

context-menu-left-click.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/context-menu';
import type { ContextMenuOpenedChangedEvent } from '@vaadin/context-menu';
import '@vaadin/grid';
import type { Grid } from '@vaadin/grid';
import { getPeople } from 'Frontend/demo/domain/DataService';
import type Person from 'Frontend/generated/com/vaadin/demo/domain/Person';
import { applyTheme } from 'Frontend/generated/theme';

@customElement('context-menu-left-click')
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;
  }

  // tag::snippet[]
  @state()
  private items = [{ text: 'View' }, { text: 'Edit' }, { text: 'Delete' }];
  // end::snippet[]

  @state()
  private gridItems: Person[] = [];

  private contextMenuOpened?: boolean;

  private onClick = (e: MouseEvent) => {
    // Prevent opening context menu on header row click.
    const target = e.currentTarget as Grid<Person>;
    if (!this.contextMenuOpened && target.getEventContext(e).section !== 'body') {
      e.stopPropagation();
    }
  };

  protected override async firstUpdated() {
    this.gridItems = (await getPeople({ count: 5 })).people;
  }

  protected override render() {
    return html`
      <!-- tag::snippethtml[] -->
      <vaadin-context-menu
        open-on="click"
        .items=${this.items}
        @opened-changed="${(event: ContextMenuOpenedChangedEvent) => {
          this.contextMenuOpened = event.detail.value;
        }}"
      >
        <vaadin-grid all-rows-visible .items=${this.gridItems} @click=${this.onClick}>
          <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 header="Phone number" path="address.phone"></vaadin-grid-column>
        </vaadin-grid>
      </vaadin-context-menu>
      <!-- end::snippethtml[] -->
    `;
  }
}
ContextMenuLeftClick.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.demo.domain.DataService;
import com.vaadin.demo.domain.Person;
import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.grid.contextmenu.GridContextMenu;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.router.Route;

import java.util.List;

@Route("context-menu-left-click")
public class ContextMenuLeftClick extends Div {

    private List<Person> people = DataService.getPeople(5);

    public ContextMenuLeftClick() {
        Grid<Person> grid = new Grid();
        grid.setAllRowsVisible(true);
        grid.setItems(people);

        grid.addColumn(person -> person.getFirstName()).setHeader("First name");
        grid.addColumn(person -> person.getLastName()).setHeader("Last name");
        grid.addColumn(person -> person.getEmail()).setHeader("Email");
        grid.addColumn(person -> person.getAddress().getPhone())
                .setHeader("Phone number");

        // tag::snippet[]
        GridContextMenu<Person> menu = grid.addContextMenu();
        menu.setOpenOnClick(true);
        menu.addItem("View", event -> {
        });
        menu.addItem("Edit", event -> {
        });
        menu.addItem("Delete", event -> {
        });
        // end::snippet[]

        add(grid);
    }

}

Best Practices

Context Menu is used to provide shortcuts to the user. You shouldn’t use it as the only or primary means to complete a task. The primary way should be accessible elsewhere in the UI.

Important

Open the Context Menu by right-clicking (desktop) or long-pressing (mobile) a Grid row, or use the Menu Bar in the last column.

Open in a
new tab

Source code

context-menu-best-practices.tsimport { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import '@vaadin/context-menu';
import '@vaadin/grid';
import { columnBodyRenderer } from '@vaadin/grid/lit.js';
import type { Grid } from '@vaadin/grid';
import '@vaadin/menu-bar';
import { applyTheme } from 'Frontend/generated/theme';

interface FileItem {
  name: string;
  size: string;
}

@customElement('context-menu-best-practices')
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;
  }

  // tag::snippet[]
  @state()
  private items = [{ text: 'View' }, { text: 'Edit' }, { text: 'Delete' }];
  // end::snippet[]

  @state()
  private gridItems: FileItem[] = [
    { name: 'Annual Report.docx', size: '24 MB' },
    { name: 'Financials.xlsx', size: '42 MB' },
  ];

  protected override render() {
    return html`
      <!-- tag::snippethtml[] -->
      <vaadin-context-menu .items=${this.items}>
        <vaadin-grid
          all-rows-visible
          .items=${this.gridItems}
          @vaadin-contextmenu=${this.onContextMenu}
        >
          <vaadin-grid-column path="name"></vaadin-grid-column>
          <vaadin-grid-column path="size"></vaadin-grid-column>
          <vaadin-grid-column
            width="70px"
            flex-grow="0"
            ${columnBodyRenderer(
              () => html`
                <vaadin-menu-bar
                  .items=${[{ component: this.makeIcon(), children: this.items }]}
                  theme="tertiary"
                ></vaadin-menu-bar>
              `,
              []
            )}
          ></vaadin-grid-column>
        </vaadin-grid>
      </vaadin-context-menu>
      <!-- end::snippethtml[] -->
    `;
  }

  makeIcon() {
    const item = document.createElement('vaadin-context-menu-item');
    item.textContent = '•••';
    item.setAttribute('aria-label', 'More options');
    return item;
  }

  onContextMenu(e: MouseEvent) {
    // Prevent opening context menu on header row.
    const target = e.currentTarget as Grid<FileItem>;
    if (target.getEventContext(e).section !== 'body') {
      e.stopPropagation();
    }
  }
}
ContextMenuBestPractices.javapackage com.vaadin.demo.component.contextmenu;

import com.vaadin.flow.component.contextmenu.MenuItem;
import com.vaadin.flow.component.contextmenu.SubMenu;
import com.vaadin.flow.component.grid.Grid;
import com.vaadin.flow.component.grid.contextmenu.GridContextMenu;
import com.vaadin.flow.component.html.Div;
import com.vaadin.flow.component.menubar.MenuBar;
import com.vaadin.flow.component.menubar.MenuBarVariant;
import com.vaadin.flow.router.Route;

import static org.apache.commons.io.FileUtils.byteCountToDisplaySize;

@Route("context-menu-best-practices")
public class ContextMenuBestPractices extends Div {

    public ContextMenuBestPractices() {
        Grid<File> grid = new Grid();
        grid.setAllRowsVisible(true);
        grid.setItems(getFiles());

        grid.addColumn(File::getName).setHeader("Name");
        grid.addColumn(File::getDisplaySize).setHeader("Size");
        // tag::snippet[]
        grid.addComponentColumn(file -> {
            MenuBar menuBar = new MenuBar();
            menuBar.addThemeVariants(MenuBarVariant.LUMO_TERTIARY);
            MenuItem menuItem = menuBar.addItem("•••");
            menuItem.getElement().setAttribute("aria-label", "More options");
            SubMenu subMenu = menuItem.getSubMenu();
            subMenu.addItem("Preview", event -> {
            });
            subMenu.addItem("Edit", event -> {
            });
            subMenu.addItem("Delete", event -> {
            });
            return menuBar;
        }).setWidth("70px").setFlexGrow(0);

        GridContextMenu<File> menu = grid.addContextMenu();
        menu.addItem("Preview", event -> {
        });
        menu.addItem("Edit", event -> {
        });
        menu.addItem("Delete", event -> {
        });
        // end::snippet[]

        add(grid);
    }

    private File[] getFiles() {
        return new File[] { new File("Annual Report.docx", 25165824),
                new File("Financials.xlsx", 44040192) };
    }

    private class File {

        private String name;
        private long size;

        File(String name, long size) {
            this.name = name;
            this.size = size;
        }

        public String getName() {
            return name;
        }

        public long getSize() {
            return size;
        }

        public String getDisplaySize() {
            return byteCountToDisplaySize(size);
        }
    }

}

You should use Context Menu when there is no dedicated button for opening an overlay menu, such as right-clicking a grid row. When there is a dedicated element/component, such as an overflow menu, use Menu Bar.

Icons

Use icons when applicable to help improve recognition. It’s recommended to use commonly recognized icons to avoid confusion. Use icons consistently throughout a list of options.

Labelling

Suffix a menu item with “…” when the associated action won’t be executed, but instead reveal some UI, like a dialog, for completing the action.

Component	Usage recommendations
Menu Bar	Component for displaying a horizontal menu with multi-level sub-menus.

Component

Usage recommendations

Menu Bar

Component for displaying a horizontal menu with multi-level sub-menus.

760AB528-B02C-4B6C-BB27-D7EFEDAE706E

Documentation

Documentation

Context Menu

Dividers

Checkable Menu Items

Hierarchical Menu

Custom Items

Disabled Menu Items

Left-Click

Best Practices

Context Menu vs Menu Bar

Icons

Labelling

Documentation

Dividers

Checkable Menu Items

Hierarchical Menu

Custom Items

Disabled Menu Items

Left-Click

Best Practices

Context Menu vs Menu Bar

Icons

Labelling

Related Components