> Markdown version of [Context Menu](https://vaadin.com/docs/v23/components/context-menu). Section index: [llms.txt](https://vaadin.com/docs/v23/components/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.

**TypeScript** — `context-menu-basic.ts`

```html
@state()
private items = [{ text: 'View' }, { text: 'Edit' }, { text: 'Delete' }];

...

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

**Java** — `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.

**TypeScript** — `context-menu-dividers.ts`

```typescript
<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>
```

**Java** — `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.

**TypeScript** — `context-menu-checkable.ts`

```typescript
@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];
}
```

**Java** — `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.

**TypeScript** — `context-menu-hierarchical.ts`

```typescript
@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' },
];

...

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

**Java** — `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.

**TypeScript** — `context-menu-presentation.ts`

```typescript
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') },
  ];
}

...

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

**Java** — `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.

**TypeScript** — `context-menu-disabled.ts`

```typescript
@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 },
];

...

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

**Java** — `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 doesn’t have any other function, for example a Grid without selection support.

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

**TypeScript** — `context-menu-left-click.ts`

```typescript
@state()
private items = [{ text: 'View' }, { text: 'Edit' }, { text: 'Delete' }];

...

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

**Java** — `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 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.

**TypeScript** — `context-menu-best-practices.ts`

```typescript
@state()
private items = [{ text: 'View' }, { text: 'Edit' }, { text: 'Delete' }];

...

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

**Java** — `ContextMenuBestPractices.java`

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

### <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/v23/components/menu-bar.md), use Menu Bar.

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

### <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/v23/components/menu-bar.md) | Component for displaying a horizontal menu with multi-level sub-menus. |

`760AB528-B02C-4B6C-BB27-D7EFEDAE706E`
