Skip to content
Nana UI

Navigation

Context Menu

A menu of commands that replaces the browser's own when someone right-clicks, long-presses or presses the Menu key over an area.

View .md Download

The context menu puts the commands for a thing where the pointer already is: right-click a file, a table row or a canvas and choose what to do with it. It replaces the browser’s own menu over the area it wraps, and nowhere else. People who never right-click never find it, so every command in it must also be reachable another way, such as a menu button on the row.

Right-click the area, long-press it on a touch screen, or focus the button and press Shift+F10.

NIC-2041 Open Renew Copy number Transfer
Cancel policy

Nothing chosen yet

Nothing chosen yet

Install the package for a versioned dependency:

npm install @nana-tec/ui-components

Or copy the source in and own it:

npx @nana-tec/ui add context-menu --framework web-components
npx @nana-tec/ui add context-menu --framework svelte

Lands in src/lib/components/ui/context-menu/ as NanaContextMenu.svelte, with the dropdown’s item, label and separator, which it shares. Styled with Tailwind classes that resolve to the design tokens. Requires Tailwind v4.

The content is the area; the menu snippet holds the items.

<script lang="ts">
import {
NanaContextMenu,
NanaContextMenuItem,
NanaContextMenuSeparator,
} from '$lib/components/ui/context-menu';
</script>
<NanaContextMenu label="File actions">
<FileRow {file} />
{#snippet menu()}
<NanaContextMenuItem onclick={() => open(file)}>Open</NanaContextMenuItem>
<NanaContextMenuItem href={`/files/${file.id}/history`}>History</NanaContextMenuItem>
<NanaContextMenuSeparator />
<NanaContextMenuItem destructive onclick={() => remove(file)}>Delete</NanaContextMenuItem>
{/snippet}
</NanaContextMenu>

An item takes onclick, or href to make it a link, plus disabled and destructive. Calling preventDefault() in onclick keeps the menu open. open is bindable.

Import the autoloader once, in your app's entry point. Every <nana-*> tag then works anywhere, and each component downloads only the first time a page uses it:

import "@nana-tec/ui-components/autoloader";
import "@nana-tec/ui-components/theme";

The second line gives every component the Nana look and the design tokens behind it. Leave it out to style the components entirely yourself.

Import a component directly when it must be ready at once: on screen at first paint, or when you call its methods straight away. The two mix freely:

import "@nana-tec/ui-components/context-menu";

Copied in with npx @nana-tec/ui add context-menu? Import your project's own @/lib/nana-ui/autoloader.js once instead; the CLI keeps it up to date.

The content is the area; children with slot="menu" are the items.

<nana-context-menu label="File actions">
<div class="file-row">report.pdf</div>
<nana-menu-item slot="menu" value="open">Open</nana-menu-item>
<nana-menu-item slot="menu" value="history" href="/files/report/history">History</nana-menu-item>
<hr slot="menu" />
<nana-menu-item slot="menu" value="delete" destructive>Delete</nana-menu-item>
</nana-context-menu>
<script type="module">
document.querySelector('nana-context-menu').addEventListener('nana-select', (event) => {
console.log(event.detail.value);
});
</script>

Items are menu items, with their icons, shortcuts and states. nana-select fires for the chosen one, and nana-open and nana-close as the menu opens and closes.

  • A right-click, or a long press on a touch screen, opens the menu at the pointer. A second right-click moves it there.
  • Shift+F10 or the Menu key opens it below the focused element, on its first item.
  • Near the window’s edges it opens upwards or moves in, so it is never cut off.
  • Choosing an item, Escape, Tab, a press outside, scrolling or resizing the window closes it.
  • Set disabled to give the area the browser’s own menu back.
KeyDoes
Shift+F10 or MenuOpens the menu on the first item
Up and Down arrowsMove between items, skipping disabled ones
Home and EndGo to the first or last item
A letterGoes to the next item starting with it
Enter or SpaceChooses the item
EscapeCloses the menu and returns focus
TabCloses the menu and moves on
  • The menu is named by label, “Actions” by default; name it after the thing it acts on, such as “File actions”.
  • Focus goes back to where it was when the menu closes.
  • A context menu is never the only way to a command. Screen reader and keyboard users rarely look for one, and many touch users never long-press.

Properties

PropertyAttributeTypeDefaultDescription
disableddisabledbooleanfalseLeave the browser's own menu in place
labellabelstring''Names the menu for screen readers
openopenbooleanfalseWhether the panel is open. Set it to open or close the panel yourself.

Methods

MethodDescription
hide(returnFocus: unknown): voidClose the menu, putting focus back where it was

Events

EventDescription
nana-openAfter the menu opens
nana-closeAfter the menu closes
nana-selectBubbled from a chosen item (detail.value)

Slots

SlotDescription
(default)The area the menu belongs to
menunana-menu-item / nana-menu-label / <hr> children

CSS parts

PartDescription
::part(panel)The menu

CSS custom properties

PropertyDescription
--nana-context-menu-min-widthNarrowest the menu may be
--nana-context-menu-zStacking order for the menu

NanaContextMenu

PropTypeDefault
labelstring
disabledbooleanfalse
openbind:booleanfalse
onOpenChange(open: boolean) => void
menuSnippet
childrenSnippet

Also accepts Omit<HTMLAttributes<HTMLDivElement>, 'class'>.