react-native-ios-context-menu v2.5.1

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.

Versions

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

Table of Contents

TOC: Examples Index

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.

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

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 (
    <ContextMenuView
      style={styles.container}
      menuConfig={{
        menuTitle: 'BasicUsageExample01',
        menuItems: [{
          actionKey  : 'key-01',
          actionTitle: 'Action #1',
        }, {
          actionKey  : 'key-02'   ,
          actionTitle: 'Action #2',
        }, {
          actionKey  : 'key-03'   ,
          actionTitle: 'Action #3',
        }],
      }}
    >
      <Text style={styles.text}>
        Press And Hold To Show Context Menu
      </Text>
    </ContextMenuView>
  );
};

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

ContextMenuView Component: Event Props

ContextMenuView Component: Properties/Methods

ContextMenuView Component: Experimental - Auxiliary Preview

The context menu auxiliary preview is an experimental feature, and is not officially part of UIKit's "Menu and Shortcuts" API.

This is just a feature that I've implemented myself and added to the library — as such official support is limited and might break in a future iOS version. Please use at your own risk.

ContextMenuButton Component

For basic usage, please see Example 1 section.

• The ContextMenuButton component is almost the same as the ContextMenuView component (It supports the same kind of props and events).

• The only difference between them is that the ContextMenuButton component does not have a preview, and it can be immediately shown when its tapped instead of having to do a long press. See Example 2 for more details.

• Note that ContextMenuButton is only available on iOS 14 and above. On iOS 13, it will use a ContextMenuButton, and on iOS 12 and below, it will use the ActionSheetFallback module to present a ActionSheetIOS menu.

• If you want to add additional touch events, you can wrap this component inside a button component (e.g. TouchableOpacity). * When wrapping this component inside a button, please make sure to set the useActionSheetFallback prop to false.

ContextMenuButton Component: Props

ContextMenuButton Component: Event Props

ContextMenuButton Component: Properties/Methods

ActionSheetFallback Module

A module to show a ActionSheetIOS menu based on a MenuConfig object.

This module attempts to approximate UIMenu behavior using ActionSheetIOS, so it's very limited (i.e. it does not support menu/action icons, etc.), but it does support things like submenu's, destructive actions/menu's, inline submenu's, and hidden actions.

• Import the module like this: import { ActionSheetFallback } from "react-native-ios-context-menu";

• To present a ActionSheetIOS menu, call const selectedAction = await ActionSheetFallback.show(menuConfig)

D.2. Context

ContextMenuViewContext Context

TBA

ContextMenuButtonContext Context

TBA

D.3. Hooks

useMenuContext Hook

A hook to use the ContextMenuViewContext context.

TBA

useMenuButtonContext Hook

A hook to use the ContextMenuButtonContext context.

TBA

D.4. Objects and Types

MenuConfig.ts

• 📌 Declaration: MenuConfig.ts

Object Type: MenuConfig

A container for grouping related menu elements in an app menu or contextual menu.

An object that is used to create and configure a context menu. Internally, this object is used to create a UIMenu instance (see apple docs for more information).

Object Type: MenuActionConfig

An object that is used to create a menu action item in the context menu. Internally, this object is used to create a UIAction instance (see apple docs for more information),

Object Type: DeferredMenuElementConfig

An object that is used to create a deferred menu element. Internally, this object is used to create a UIDeferredMenuElement instance (see apple docs for more information),

String Union: MenuAttributes

Attributes that determine the style of the menu element.

A union string type that maps to UIMenuElement.Attributes enum (see apple docs for more information).

String Union: MenuState

Constants that indicate the state of an action- or command-based menu element.

A union string type that maps to UIMenuElement.State enum (see apple docs for more information).

String Union: UIMenuOptions

Options for configuring a menu's appearance.

A union string type that maps to UIMenu.Options option set (see apple docs for more information).

String Union: MenuElementSize

Constants that determine the size of an element in a menu.

A union string type that maps to UIMenu.ElementSize enum (see apple docs for more information).

MenuPreviewConfig.ts

• 📌 Declaration: MenuPreviewConfig.ts

Object Type: MenuPreviewConfig

String Union: ContextMenuInteractionCommitStyle

String Union: MenuPreviewSize

String Union: MenuPreviewType

MenuAuxiliaryPreviewConfig.ts

• 📌 Declaration: MenuAuxiliaryPreviewConfig.ts

Object Type: MenuAuxiliaryPreviewConfig

String Union Type: MenuAuxiliaryPreviewAnchorPosition

String Union Type: MenuAuxiliaryPreviewHorizontalAlignment

String Union Type: UIViewAnimateOptions

Object Type: UIViewAnimateConfig

Object Type: MenuAuxiliaryPreviewBaseTransitionConfig

This type is an object tagged union type, with the transition property being the tag that separates the unions.

The table below defines the possible valid values that can be assigned to the type property (the subsequent tables are the different possible unions).

Object Union Type: MenuAuxiliaryPreviewTransitionConfig

This type is a union between the UIViewAnimateConfig object type, and the MenuAuxiliaryPreviewBaseTransitionConfig object type.

export type MenuAuxiliaryPreviewTransitionConfig = 
  | UIViewAnimateConfig
  | MenuAuxiliaryPreviewBaseTransitionConfig;

Mixed Union Type: MenuAuxiliaryPreviewTransitionEntranceDelay.

MenuIconConfig.ts

• 📌 Declaration: MenuIconConfig.ts

Object Type: IconConfig

This has been deprecated and will be removed in a future version. Use ImageItemConfig instead. For documentation regarding IconConfig, please see the documentation in the old README.

ImageItemConfig.ts

• 📌 Declaration: ImageItemConfig.ts

Object Type: ImageItemConfig

This type is an object tagged union type, with the type property being the tag that separates the unions. The table below defines the possible valid values that can be assigned to the type property.

ImageItemConfig: IMAGE_ASSET

ImageItemConfig: IMAGE_SYSTEM

ImageItemConfig: IMAGE_EMPTY

ImageItemConfig: IMAGE_RECT

ImageItemConfig: IMAGE_GRADIENT

ImageItemConfig: IMAGE_REMOTE_URL

| 🔤 **Required