react-native-ios-context-menu

🚧⚠️ Documentation WIP ⚠️🚧

📝 Note: See TODO.md for progress.

• The documentation is incomplete (some parts/sections are marked as TBA i.e. "to be added").
• Some of the links in the documentation are broken (i.e. the URL points to PLACE_HOLDER_LINK).
• Some of the gifs/images are old, or broken.
• For now, please see the Usage And Examples section, and Showcase, Tests and Demos section for information on how to use this library.

Notice
📝 Note #1: Staring on version 2.x, this library now uses expo-modules, and contains a peer dependency to react-native-ios-utilites.
📝 Note #2: The documentation + examples are currently being rewritten. 💅 README-old.md — The old version of the documentation (archived). 💖 example/src/examples — The typescript rewrite of the examples (WIP).

Versions

Library Version	Compatibility
2.1+	Uses Expo-Modules Depends on react-native-ios-utilities@4.x Depends on ContextMenuAuxiliaryPreview iOS 13+ Xcode 15+
2.0.x	Uses Expo-Modules Depends on react-native-ios-utilities@4.x iOS 13+ Xcode 15+
1.6.2	iOS 10 to iOS 15 Xcode 12+
1.4	iOS 10 to iOS 15 Xcode 13+
1.3 and Below	iOS 10 to 14 Xcode 12+

📝 Note: Supports projects targeting iOS 10 but will use the action sheet fallback when running on iOS 12 and older.

Table of Contents

Sections and Links
A. Introduction • Gifs and Demos • Features
B. Installation • Expo • Troubleshooting --• Xcode Build Error (Swift) --• Xcode Build Error (Undefined symbol)
C. Basic Usage
D. Documentation • D.1. Components --• ContextMenuView Component ----• Props ----• Event Props ----• Properties/Methods ----• Experimental - Aux. Preview --• ContextMenuButton Component ----• Props ----• Event Props ----• Properties/Methods • D.2. Context --• ContextMenuButtonContext --• ContextMenuButtonContext • D.3. Hooks --• useMenuContext --• useMenuButtonContext • D.4. Objects and Types --• MenuConfig.ts ----• Object Type: MenuConfig ----• Object Type: MenuActionConfig ----• Object Type: DeferredMenuElementConfig ----• String Union: MenuAttributes ----• String Union: MenuState ----• String Union: UIMenuOptions --• MenuPreviewConfig.ts ----• Object Type: MenuPreviewConfig ----• String Union: ContextMenuInteractionCommitStyle ----• String Union: MenuPreviewSize ----• String Union: MenuPreviewType --• MenuAuxiliaryPreviewConfig.ts ----• Object Type: MenuAuxiliaryPreviewConfig ----• String Union Type: MenuAuxiliaryPreviewAnchorPosition ----• String Union Type: MenuAuxiliaryPreviewHorizontalAlignment ----• String Union Type: UIViewAnimateOptions ----• Object Type: UIViewAnimateConfig ----• Object Type: MenuAuxiliaryPreviewBaseTransitionConfig ----• Object Union Type: MenuAuxiliaryPreviewTransitionConfig ----• Mixed Union Type: MenuAuxiliaryPreviewTransitionEntranceDelay --• MenuIconConfig.ts --• ImageItemConfig.ts ----• Object Type: ImageItemConfig ----• Object Type: ImageResolvedAssetSource ----• Object Type: ImageRectConfig ----• Object Type: ImageGradientConfig ----• Object Type: ImageSystemConfig --• Undocumented Types • D.5. Constants
E. Usage And Examples 📝 Note: See Example Index section for a complete list of examples + their descriptions.
F. Showcase, Tests and Demos
G. Meta
H. Licence

TOC: Examples Index

Examples
📌 ContextMenuView Example 01 💭 Summary: A basic context menu that has 3 menu action items.
📌 ContextMenuView Example 02 💭 Summary: Icon Example — A basic context menu that has 3 menu action items, each with a different "SF Symbols" icon. This examples shows how to add a system icon in the context menu action.
📌 ContextMenuView Example 03 💭 Summary: Nested Menu — This example shows a context menu that has a submenu item inside its list of menu actions.
📌 ContextMenuView Example 04 💭 Summary: Menu Attributes — This example context menu showcases the MenuActionConfig.menuAttributes property.
📌 ContextMenuView Example 05 💭 Summary: Nested Menu + Menu Attributes — A context menu that has a in-line submenu.
📌 ContextMenuView Example 06 💭 Summary: Menu Options — A context menu that has a destructive submenu.
📌 ContextMenuView Example 07 💭 Summary: Menu Options — A context menu that set to be both "destructive" and "display in-line".
📌 ContextMenuView Example 08 💭 Summary: Menu State — A context menu with 3 actions that has 'on', 'off', and 'mixed' menuState.
📌 ContextMenuView Example 09 💭 Summary: Events — An example for the onPressMenuItem event prop.
📌 ContextMenuView Example 10 💭 Summary: Dynamic Menu — An example showing how to dynamically update the context menu while it's visible. In this example, the menu action changes every time the counter increments every second.
📌 ContextMenuView Example 11 💭 Summary: Context Menu Previews — An example showing how to use a custom preview for the context menu.
📌 ContextMenuView Example 12 💭 Summary: Context Menu Previews — An example showing a custom context menu preview that dynamically changes its size due to its contents updating every second.
📌 ContextMenuView Example 13 💭 Summary: Menu Action — An example showing how to add a subtitle to menu action.
📌 ContextMenuView Example 14 💭 Summary: Context Menu Previews — An example that changes the exit transition of the context menu preview when its tapped using the preferredCommitStyle config.
📌 ContextMenuView Example 15 💭 Summary: Context Menu Previews — An example showing how to configure a context menu that uses targeted previews.
📌 ContextMenuView Example 15-02 💭 Summary: Context Menu Previews (Cont). — An example showing how to configure a context menu that uses targeted previews + WrapperView.
📌 ContextMenuView Example 16 💭 Summary: Icon Example — An example showing a context menu with an action that uses a 'IMAGE_ASSET' image for its icon.
📌 ContextMenuView Example 17 💭 Summary: Icon Example — An example showing a context menu with action items that have different colored icons.
📌 ContextMenuView Example 18 💭 Summary: Icon Example — An example showing a context menu with action items that has icons that uses local image assets imported via require(...).
📌 ContextMenuView Example 19 💭 Summary: Dynamic Menu — An example showing a context menu that has a loading indicator using deferred menu elements.
📌 ContextMenuView Example 20 💭 Summary: Dynamic Menu — An example showing a state-controlled context menu that shows a loading indicator using deferred menu elements.
📌 ContextMenuView Example 21 💭 Summary: Menu Element Size — TBA
📌 ContextMenuView Example 22 💭 Summary: Menu Element Size — TBA
📌 ContextMenuView Example 23 💭 Summary: Menu Element Size — TBA
📌 ContextMenuView Example 24 💭 Summary: Menu Attributes — keepsMenuPresented
📌 ContextMenuView Example 25 💭 Summary: Icon Example — Advanced customization (E.g. scale, weight, paletteColors, hierarchicalColor).
📌 ContextMenuView Example 26 💭 Summary: Icon Example — Network/Remote images as icons.
📌 ContextMenuView Example 27 💭 Summary: Icon Example — Network/Remote images as icons + fallback image.
📌 ContextMenuView Example 28 💭 Summary: Programmatically shows the context menu.
📌 ContextMenuView Auxiliary Preview - Example 01 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 02 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 03 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 04 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 05 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 06 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 07 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 08 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 09 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 10 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 11 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 12 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 13 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 14 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 15 💭 Summary: TBA
📌 ContextMenuView Auxiliary Preview - Example 16 💭 Summary: Programmatically shows the auxiliary preview as a popover (w/o showing the context menu).
📌 ContextMenuButton Example 01 💭 Summary: TBA
📌 ContextMenuButton Example 02 💭 Summary: TBA

A. Introduction

A react native component to use UIMenu on iOS 13 and later.

Gifs and Demos

📝 Note: These gifs are from an older version of the library running on iOS 13 (see Usage And Examples section for updated example gifs).

ContextMenuView Examples, Left: Example 1, Example 2, and Right: Example 3, Example 4

ContextMenuView examples, Left: Example 5, Example 6, and Right: Example 7, Example 8

ContextMenuView example, Left: Example 9, and Right: Example 10

ContextMenuView examples, Left: Example 11, Example 12, and Right: Example 13, Example 14

ContextMenuView examples, Left: Example 15, Example 16, and Right: Example 17, Example 18

ContextMenuView tests, Left: Test 1, and Right: Test 2

ContextMenuView tests, Left: Test 3, and Right: Test 4

ContextMenuView tests, Left: Test 5, and Right: Test 6

ContextMenuView tests, Left/Right: Test 7

ContextMenuView ActionSheetIOS fallback for simple example 1 to 9

ContextMenuView ActionSheetIOS fallback for context menu view test 1 to 6

ContextMenuButton examples, Left: Example 1, and Right: Example 2

Features

• Support for creating menu actions and submenus (i.e. nested and in-line menus).
• Support for customizing the menu icons (i.e. support for SF Symbols, require(image), and xcasset icons, icon tint, etc).
• Extensive support for SF Symbols configuration (e.g. pointSize, weight, scale, hierarchicalColor, paletteColors).
• Support for iOS 14 functionality (like the UIButton context menu, dynamically updating the menu while it's visible, etc).
• Support for setting (almost) all of the native UIMenu and UIAction properties (e.g. UIMenuElementState, MenuElementAtrributes, discoverabilityTitle, etc.)
• Basic ActionSheetIOS menu fallback for iOS 12 and below.
• Support for creating custom context menu previews (with support for dynamic or fixed preview sizes, setting the UIPreviewParameters, specifying a UITargetedPreview, etc).
• Support for custom auxiliary previews (experimental).
• Support for deferred context menu items.

B. Installation

# 1. install library + dependencies
npm install react-native-ios-utilities
npm install react-native-ios-context-menu

# 2. then run pod install (uses auto-linking)
cd ios && pod install

📝 Note A: You might encounter some build errors since this library is written in swift, so there's some extra step involved to use this library (see table below for reference).

📝 Note B: If you want to use an older or different version of this library, please refer to versions section's compatibility table.

Additional Steps
1️⃣ Add an empty swift file to your project
2️⃣ Update the project's "Library Search Paths" build settings

Installation (Experimental Version)

# 1. install library + dependencies
npm install react-native-ios-utilities@next
npm install react-native-ios-context-menu@next


# 2. then run pod install (uses auto-linking)
cd ios && pod install

Updating

This library has cocoapods dependency to ContextMenuAuxiliaryPreview, so you need to update it separately.

# A. Either update this specific pod...
pod update ContextMenuAuxiliaryPreview

# B. Or update all the pods
pod update

Expo

• ✅ You can use this library with Development Builds. No config plugin is required.
• ❌ This library can't be used in the "Expo Go" app because it requires custom native code.

Versions and Dependencies

Library Version	Dependencies + Versions
2.0.x	react-native-ios-utilities - 4.x
2.1.x	react-native-ios-utilities - 4.x ContextMenuAuxiliaryPreview - 0.1.x
2.2.x	react-native-ios-utilities - 4.x ContextMenuAuxiliaryPreview - 0.2.x

Troubleshooting

If you encounter any errors/bugs while using this library, or want a particular feature implemented, please create an issue! (my inbox is a mess, please feel free to tag me). ✨

Troubleshooting: Xcode Build Error (Swift)

📝 Note: This library is written in swift. If you are having trouble building your app after installing this library, try adding an empty swift file to your project:

1. Open up your ios/project.xcworkspace project
2. On the project navigator panel (located on the right side of Xcode), right click on your project group (or another folder/group i.e the blue or yellow icons) and select the "New File..." option
3. In the popup sheet, select "Swift" as the template and then click the "Next" button
4. A "Save As" popup sheet should appear and then click "Create" (you can rename the file first if you want to)
5. If Xcode asks you to create a "Objective-C Bridging Header" choose "Create Objective-C Bridging Header"

Troubleshooting: Xcode Build Error (Undefined symbol)

When installing this library on Xcode 12+, you'll get the following error in Xcode:

Undefined symbol: (extension in UIKit):
__C.UIMenu.init(title: Swift.String, image: __C.UIImage?, identifier: __C.UIMenuIdentifier?, options: __C.UIMenuOptions, children: [__C.UIMenuElement]) -> __C.UIMenu

Undefined symbol: (extension in UIKit):
__C.UIAction.init(title: Swift.String, image: __C.UIImage?, identifier: __C.UIActionIdentifier?, discoverabilityTitle: Swift.String?, attributes: __C.UIMenuElementAttributes, state: __C.UIMenuElementState, handler: (__C.UIAction) -> ()) -> __C.UIAction

To fix this, see screenshot + follow the steps below:

1. Open your ios/project.xcworkspace project.
2. In the project navigator panel (located on the right side of Xcode), select your project group (i.e. the item with the blueprint icon).
3. The Xcode project editor should appear. In the left panel, under the "Project" section, select your project (if it isn't already selected).
4. In the project section's top tab bar, select the "Build Settings" tab (also make sure the "All" and "Combined" tabs are selected).
5. In the project navigator list, under the "Search Path" section, there should be a "Library Search Paths" setting (alternatively, you can search for "Library Search Paths" in the search bar).
6. According to this issue comment, you can clear all the items listed in the "Library Search Paths" setting by selecting the items in the list, and pressing the "-" button in the popover.
   • TLDR: Xcode automatically manages this setting, and the RN template hardcodes it to use Swift 5.0.
   • Alternatively, you can change the entry "$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)" to "$(TOOLCHAIN_DIR)/usr/lib/swift-5.3/$(PLATFORM_NAME)" i.e. change swift-5.0 to swift-5.3, or whatever the newest version of swift that comes with your Xcode installation (to show the popup dialog, double click the value/item).
7. If you haven't already, make sure to create an empty swift file. Then clean the build folder (the option is in the menu bar under: "Product" -> "Clean Build Folder") and try building your project again.
8. If you are still having problems building the app, try the following and build your project again:

• Try clearing out Xcode's derivedData directory: rm -rf ~/Library/Developer/Xcode/DerivedData/* (check out this gist for instructions on how to clean up Xcode)
• Try clearing out the Cocoapods cache: rm -rf "${HOME}/Library/Caches/CocoaPods" (and then try running pod install again).

Explanation: Some versions of the react-native template hard codes the swift library search paths to use swift 5.0 (which causes the linker to mismatch the swift system libraries bundled with your Xcode + iOS/Simulator installation).

Here are some related issues in the RN repo: Issue 30202 and Issue 29178.

C. Basic Usage

For more examples, check out the Usage And Examples section.

🔗 Full Example

import * as React from 'react';
import { StyleSheet, Text } from 'react-native';

import { ContextMenuView } from 'react-native-ios-context-menu';

export function BasicUsageExample01() {
  return (
    
      
    
  );
};

const styles = StyleSheet.create({
  container: {
    margin: 10,
    padding: 10,
  },
  text: {
    fontSize: 16,
  },
});

D. Documentation

💡 Tip: Most of the time, when a type or component is mentioned, you can click it to jump to that item in the README (or its declaration in the source code).

D.1. Components

ContextMenuView Component

ContextMenuView Component: Props

Prop Name and Type	Description
⚛️ ViewProps	This component supports all the standard props from a `