> Markdown version of [Context Menu](https://vaadin.com/docs/v14/ds/components/context-menu). Section index: [llms.txt](https://vaadin.com/docs/v14/ds/llms.txt)

# Context Menu

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.

`ContextMenuBasic.java`

```java
GridContextMenu<Person> menu = grid.addContextMenu();
menu.addItem("View", event -> {});
menu.addItem("Edit", event -> {});
menu.addItem("Delete", event -> {});
```

## <a id="dividers"></a>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.

`ContextMenuDividers.java`

```java
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 -> {});
```

## <a id="checkable-menu-items"></a>Checkable Menu Items

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

`ContextMenuCheckable.java`

```java
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));

...

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());
}
```

## <a id="hierarchical-menu"></a>Hierarchical Menu

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.

`ContextMenuHierarchical.java`

```java
GridContextMenu<File> menu = grid.addContextMenu();
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 -> {});
```

## <a id="custom-items"></a>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.

`ContextMenuPresentation.java`

```java
GridContextMenu<Person> menu = grid.addContextMenu();
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 -> {});
});

...

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;
}
```

## <a id="disabled-menu-items"></a>Disabled Menu Items

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.

`ContextMenuDisabled.java`

```java
GridContextMenu<File> menu = grid.addContextMenu();

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

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

## <a id="left-click"></a>Left-Click

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

> **Important:** Open the Context Menu by clicking a Grid row.

`ContextMenuLeftClick.java`

```java
GridContextMenu<Person> menu = grid.addContextMenu();
menu.setOpenOnClick(true);
menu.addItem("View", event -> {});
menu.addItem("Edit", event -> {});
menu.addItem("Delete", event -> {});
```

## <a id="best-practices"></a>Best Practices

Context Menu is used to provide shortcuts to the user. You should not 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.

`ContextMenuBestPractices.java`

```java
grid.addComponentColumn(file -> {
  MenuBar menuBar = new MenuBar();
  menuBar.addThemeVariants(MenuBarVariant.LUMO_TERTIARY_INLINE);
  MenuItem menuItem = menuBar.addItem("•••");
  menuItem.getElement().setAttribute("aria-label", "More options");
  return menuBar;
})
  .setAutoWidth(true)
  .setFlexGrow(0);

GridContextMenu<File> menu = grid.addContextMenu();
menu.addItem("Preview", event -> {});
menu.addItem("Edit", event -> {});
menu.addItem("Delete", event -> {});
```

### <a id="context-menu-vs-menu-bar"></a>Context Menu vs Menu Bar

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](https://vaadin.com/docs/v14/ds/components/menu-bar.md), use Menu Bar.

### <a id="icons"></a>Icons

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

### <a id="labelling"></a>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.

## <a id="related-components"></a>Related Components

| Component                                                         | Usage recommendations                                                  |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Menu Bar](https://vaadin.com/docs/v14/ds/components/menu-bar.md) | Component for displaying a horizontal menu with multi-level sub-menus. |

`2521898B-8802-40FC-BD68-1D5251EAB787`