react-native-nitro-contextmenu

Native context menus built with Nitro Modules. Supports actions, submenus, selection state, inline groups, palettes, tabbed menus, and tap-to-trigger.

Installation

npm install react-native-nitro-contextmenu react-native-nitro-modules

For iOS, install pods:

cd ios && pod install

Android requires no additional setup.

Quick Start

import { ContextMenu } from "react-native-nitro-contextmenu";
import type { MenuConfig } from "react-native-nitro-contextmenu";

function MyComponent() {
  const menuConfig: MenuConfig = {
    title: "",
    items: [
      { actionKey: "copy", title: "Copy", image: { systemName: "doc.on.doc" } },
      { actionKey: "paste", title: "Paste", image: { systemName: "doc.on.clipboard" } },
      {
        actionKey: "delete",
        title: "Delete",
        image: { systemName: "trash" },
        attributes: ["destructive"],
      },
    ],
  };

  return (
    <ContextMenu menuConfig={menuConfig} onPressAction={(key) => console.log("Selected:", key)}>
      <View style={{ padding: 20 }}>
        <Text>Tap me</Text>
      </View>
    </ContextMenu>
  );
}

Props

| Prop | Type | Description | | ----------------- | ----------------------------- | --------------------------------------------------------- | | menuConfig | MenuConfig | Required. The menu structure to display. | | trigger | 'tap' \| 'longPress' | How the menu is triggered. Default: 'tap'. | | onPressAction | (actionKey: string) => void | Called when a menu action is selected. | | onMenuWillShow | () => void | Called when the menu is about to appear. | | onMenuWillHide | () => void | Called when the menu is about to disappear. | | onPreviewPress | () => void | Called when the user taps the preview (iOS only). | | previewConfig | PreviewConfig | Customize the preview appearance (iOS only). | | children | ReactNode | Required. The trigger content. |

Menu Configuration

MenuConfig

The root menu and any submenus share the same shape:

interface MenuConfig {
  title?: string;
  subtitle?: string; // iOS only
  image?: SystemImage;
  options?: MenuOption[];
  preferredElementSize?: "small" | "medium" | "large"; // iOS 16+
  tabs?: MenuTab[]; // iOS 16+ — when present, items is ignored
  items: MenuElement[];
}

MenuAction

Leaf actions that appear as tappable rows:

interface MenuAction {
  actionKey: string; // Unique key returned in onPressAction
  title: string;
  subtitle?: string; // iOS 15+
  image?: MenuImage; // SF Symbol or URL
  selectedImage?: SystemImage; // Icon when state is 'on' (iOS 17+)
  attributes?: MenuElementAttribute[];
  state?: "on" | "off" | "mixed";
  discoverabilityTitle?: string; // iOS only
}

MenuElement

A union of MenuAction | MenuConfig. The native side discriminates by checking for actionKey (action) vs items (submenu).

Images

// SF Symbol (iOS native, mapped to Android system drawables)
{
  systemName: "star.fill";
}

// URL image (iOS only)
{
  url: "https://example.com/icon.png";
}

On Android, common SF Symbol names are automatically mapped to equivalent android.R.drawable icons. You can also provide your own drawables by adding resources named with dots replaced by underscores (e.g. doc_on_doc.xml for doc.on.doc).

Options

Applied to MenuConfig.options:

| Option | iOS | Android | | -------------------- | ---------------------------------------------- | ------------------------------------------------- | | 'displayInline' | Renders children inline with a separator. | Items added to parent menu with group separators. | | 'destructive' | Renders the submenu title in red. | No visual change. | | 'singleSelection' | Only one child can be state: 'on' at a time. | Exclusive checkable group. | | 'displayAsPalette' | Renders children as a horizontal icon row. | No effect (renders as normal items). |

Attributes

Applied to MenuAction.attributes:

| Attribute | iOS | Android | | ---------------------- | ---------------------------------------- | ------------------------- | | 'destructive' | Red text and icon. | Icon tinted red. | | 'disabled' | Grayed out, not tappable. | Grayed out, not tappable. | | 'hidden' | Not visible in the menu. | Not visible in the menu. | | 'keepsMenuPresented' | Menu stays open after tapping (iOS 16+). | No effect. |

Examples

Submenus

Nest MenuConfig objects inside items to create submenus:

const menuConfig: MenuConfig = {
  title: "",
  items: [
    {
      title: "Sort By",
      image: { systemName: "arrow.up.arrow.down" },
      items: [
        { actionKey: "sort-name", title: "Name" },
        { actionKey: "sort-date", title: "Date" },
        { actionKey: "sort-size", title: "Size" },
      ],
    },
  ],
};

Single Selection

Use singleSelection with state to create radio-style groups:

const [selected, setSelected] = useState('medium')

const menuConfig: MenuConfig = {
  title: 'Text Size',
  items: [
    {
      title: '',
      options: ['displayInline', 'singleSelection'],
      items: [
        { actionKey: 'small', title: 'Small', state: selected === 'small' ? 'on' : 'off' },
        { actionKey: 'medium', title: 'Medium', state: selected === 'medium' ? 'on' : 'off' },
        { actionKey: 'large', title: 'Large', state: selected === 'large' ? 'on' : 'off' },
      ],
    },
  ],
}

<ContextMenu menuConfig={menuConfig} onPressAction={setSelected}>
  {/* ... */}
</ContextMenu>

Inline Groups with Separators

Use displayInline to show items in the same level with visual separators, and preferredElementSize: 'small' for compact icon rows (iOS only):

const menuConfig: MenuConfig = {
  title: "",
  items: [
    {
      title: "",
      options: ["displayInline"],
      preferredElementSize: "small",
      items: [
        { actionKey: "cut", title: "Cut", image: { systemName: "scissors" } },
        { actionKey: "copy", title: "Copy", image: { systemName: "doc.on.doc" } },
        { actionKey: "paste", title: "Paste", image: { systemName: "doc.on.clipboard" } },
      ],
    },
    { actionKey: "select-all", title: "Select All", image: { systemName: "selection.pin.in.out" } },
  ],
};

Palette (iOS only)

Use displayAsPalette for a horizontal icon strip (e.g. color pickers). On Android, items render as a normal list.

const menuConfig: MenuConfig = {
  title: "Color",
  items: [
    {
      title: "",
      options: ["displayInline", "displayAsPalette"],
      items: [
        { actionKey: "red", title: "Red", image: { systemName: "circle.fill" } },
        { actionKey: "green", title: "Green", image: { systemName: "circle.fill" } },
        { actionKey: "blue", title: "Blue", image: { systemName: "circle.fill" } },
      ],
    },
  ],
};

Destructive & Disabled Actions

const menuConfig: MenuConfig = {
  title: "",
  items: [
    { actionKey: "edit", title: "Edit", image: { systemName: "pencil" } },
    { actionKey: "archive", title: "Archive", attributes: ["disabled"] },
    {
      title: "",
      options: ["displayInline"],
      items: [
        {
          actionKey: "delete",
          title: "Delete",
          image: { systemName: "trash" },
          attributes: ["destructive"],
        },
      ],
    },
  ],
};

Tabbed Menu (iOS 16+)

Tabs display a row of buttons at the top of the menu. Tapping a tab swaps the items below without dismissing the menu. When tabs is provided, items is ignored.

const menuConfig: MenuConfig = {
  title: "",
  tabs: [
    {
      tabKey: "sort",
      title: "Sort",
      image: { systemName: "arrow.up.arrow.down" },
      items: [
        { actionKey: "sort-name", title: "Name" },
        { actionKey: "sort-date", title: "Date" },
        { actionKey: "sort-size", title: "Size" },
      ],
    },
    {
      tabKey: "filter",
      title: "Filter",
      image: { systemName: "line.3.horizontal.decrease" },
      items: [
        { actionKey: "filter-images", title: "Images" },
        { actionKey: "filter-videos", title: "Videos" },
      ],
    },
  ],
  items: [],
};

On iOS < 16 and on Android, the tab bar is omitted and the first tab's items are shown as a flat menu.

Trigger Mode

By default, the menu opens on a single tap. Use trigger="longPress" for long-press with preview (iOS):

<ContextMenu menuConfig={menuConfig} trigger="longPress">
  <View>
    <Text>Long press me</Text>
  </View>
</ContextMenu>

On iOS, no preview is shown when trigger is 'tap'.

Preview Configuration (iOS only)

Customize the context menu preview. This has no effect on Android.

<ContextMenu
  menuConfig={menuConfig}
  previewConfig={{
    previewType: "view", // 'view' (default) or 'none'
    preferredCommitStyle: "pop", // 'pop' (default) or 'dismiss'
    backgroundColor: "#ffffff",
    borderRadius: 16,
  }}
  onPreviewPress={() => console.log("Preview tapped")}
>
  {/* ... */}
</ContextMenu>

Type Exports

All types are exported for use in your own code:

import type {
  ContextMenuProps,
  MenuConfig,
  MenuAction,
  MenuElement,
  MenuTab,
  MenuOption,
  MenuElementAttribute,
  MenuElementSize,
  MenuElementState,
  MenuImage,
  SystemImage,
  UrlImage,
  PreviewConfig,
} from "react-native-nitro-contextmenu";

Platform Support

Feature matrix

| Feature | iOS | Android | | -------------------- | ------------------------------------------ | ---------------------------- | | Actions with icons | SF Symbols + URL images | Mapped system drawables | | Submenus | Nested menus | Nested menus | | Inline groups | Separator + inline items | Group separators | | Single selection | Checkmarks | Checkmarks | | Destructive style | Red text + icon | Red icon tint | | Disabled items | Grayed out | Grayed out | | Hidden items | Excluded | Excluded | | Trigger mode | trigger="tap" (default) or "longPress" | trigger="tap" or "longPress" | | Tabbed menus | Tab bar + swappable content (iOS 16+) | First tab shown as flat menu | | Palette mode | Horizontal icon row (iOS 17+) | Normal menu items | | Preview | Customizable preview with commit styles | Not supported | | Subtitles | Below action title (iOS 15+) | Not supported | | keepsMenuPresented | Menu stays open (iOS 16+) | Not supported | | selectedImage | Alternate icon for checked state (iOS 17+) | Not supported |

iOS version requirements

| Feature | Minimum iOS | | ---------------------------------------------------------- | ----------- | | Context menus | 13.0 | | Subtitles | 15.0 | | keepsMenuPresented, preferredElementSize, tabbed menus | 16.0 | | displayAsPalette, selectedImage | 17.0 |

Features are gracefully skipped on older iOS versions and unsupported Android features.

License

MIT