react-native-ios-context-menu: bringing UIMenu to React Native

The problem is that React Native has no equivalent of UIMenu

React Native renders its own views, so the platform menus that an iOS user expects simply are not there. A long press that would open a UIMenu on a native app opens a custom menu, if the application implements one at all, and it will not look or behave like the system component.

This library is the answer to that gap. The description is plain about it: a react-native component to use context menu's, UIMenu, on iOS 13/14+, and the readme calls it a small component for using context menu's on iOS.

That word small matters. This is not a general purpose native UI toolkit. It is one platform component, wrapped for React Native, with the configuration surface of a menu: items, submenus, icons, and a preview.

The preview is the part that pushes this beyond a dropdown replacement. The documentation index lists an Experimental, Aux. Preview section under the ContextMenuView component, and a whole configuration file, MenuPreviewConfig.ts, with types for the transition style, the preview size and the preview type, plus a separate MenuIconConfig.ts and ImageItemConfig.ts for image based menu items with resolved asset sources, rectangles, gradients and system images.

So the audience is iOS React Native developers who have decided that the native menu is the right interaction and want it without leaving the React Native tree.

Two components, a context and a set of hooks

The API surface is documented in the readme index, and it is worth walking through because it tells you how the library expects to be used.

There is a ContextMenuView component, the one you attach to the view that should respond to a long press, and a ContextMenuButton component, which is the button flavoured variant. Each has its own props, event props and properties or methods sections in the documentation.

On top of those sits a context layer. The index lists a ContextMenuButtonContext under a Context section, and a D.3 Hooks section with useMenuContext and useMenuButtonContext. That combination is the interesting part of the design. A context plus a hook means the menu configuration can live above the component that triggers it, which is how you would share a single menu definition between several call sites, or drive it from a parent that owns the state.

The types are split across several files, which tells you the configuration is genuinely typed rather than a bag of loosely typed props. MenuConfig.ts holds MenuConfig, MenuActionConfig and DeferredMenuElementConfig, along with the MenuAttributes and MenuState string unions and the UIMenuOptions union. MenuPreviewConfig.ts holds the preview related types, and there are further types for the animation configuration, including UIViewAnimateOptions, UIViewAnimateConfig and the auxiliary preview transition types.

The DeferredMenuElementConfig type in particular suggests a menu item whose contents are resolved lazily, and the MenuState union suggests a state machine around whether the menu is open, which is the kind of detail you only get from a library that has been through a rewrite.

Version 3 is a rewrite, and the version table tells you what fits

The compatibility table in the readme is the single most useful thing in the repository, because it maps library versions to architecture, iOS and Xcode requirements.

Version 3.x and later depends on react-native-ios-utilities at 5.x, depends on ContextMenuAuxiliaryPreview, needs iOS 13+ and Xcode 15+. Version 2.1 uses Expo-Modules, depends on react-native-ios-utilities at 4.x, depends on ContextMenuAuxiliaryPreview, and needs iOS 13+ and Xcode 15+. Version 2.0.x is the same but on 4.x of the utilities.

Then the older lines drop the dependencies and the floor: 1.6.2 covers iOS 10 to iOS 15 with Xcode 12+, 1.4 covers iOS 10 to iOS 15 with Xcode 13+, and 1.3 and below cover iOS 10 to 14 with Xcode 12+.

The note that explains why version 3 exists is worth reading closely. Version 3.x is a rewrite of this library to support both fabric, the new architecture, and offer backwards compatibility to paper, the old architecture. Support for the new architecture and backwards compatibility for the old one is handled via a peer dependency to react-native-ios-utilities at version 5.

So a version 3 install is not an incremental update, it is a new implementation with a compatibility layer, and it pulls in a peer dependency you did not have before. That is the kind of change that needs a migration rather than a version bump, and the readme keeps the old documentation around under README-old-v1.md and README-old-v2.md for exactly that reason.

The library is in maintenance mode, and the readme says so first

The first notice in the readme is a hiatus notice, and it should shape your adoption decision more than any feature does.

The author states that they are no longer doing OSS for the time being, so the library is in maintenance mode, and invites sponsorship or a new maintainer by contact.

A second notice narrows the support policy further. Versions 2.x and below are no longer supported, and you should not submit an issue if the version you are using is below 3.x.

A third notice is about the documentation, and it is unusually specific. The documentation is incomplete, with some parts and sections marked as TBA, to be added. Some of the links in the documentation are broken, meaning the URL points to PLACE_HOLDER_LINK. And some of the gifs and images are old, or broken. The readme points you to the Usage And Examples section and the Showcase, Tests and Demos section for information on how to use the library in the meantime.

Those three notices together describe a library that works, is not being worked on, and is documented in a way that will waste some of your time. The maintenance mode is the deciding factor. The last push was on 2026-04-17, the repository is not archived, and the most recent releases are 3.1.2 on 2025-04-23, 3.1.3 on 2025-08-14 and 3.2.0 on 2025-09-11, with the manifest carrying version 3.2.2.

The code is MIT licensed, and the tree is a normal React Native library: a podspec, an ios directory, src, example and example-expo directories, and a scripts directory. The absence of a visible android implementation in the top level list is worth noting too, since the component is described as iOS only.

Installing it, and the build problems people hit

The readme's own table of contents lists an Installation section with an Expo subsection and a Troubleshooting subsection containing two specific Xcode build errors, one for Swift and one for an undefined symbol. That is the honest picture of what adoption looks like: there is an Expo path, and there are two named native build failures that the documentation addresses.

The package manifest shows the shape of the install. The package is react-native-ios-context-menu, and the published files list includes src, lib, android, ios and cpp, plus the podspec, with the build directories and the android gradle wrapper excluded.

  "main": "lib/commonjs/index",
  "module": "lib/module/index",
  "types": "lib/typescript/module/src/index.d.ts",
  "react-native": "src/index",
  "source": "src/index",

The dual export layout is the standard React Native library arrangement: a CommonJS build for older bundlers, an ES module build for modern ones, a TypeScript declaration entry point, and the source field pointing at the TypeScript source so a monorepo can consume it directly.

Two things the manifest does not settle for you. The peer dependencies are not in the visible part of the file, but the readme states them for version 3: react-native-ios-utilities at 5.x and ContextMenuAuxiliaryPreview. Those are separate packages you have to add yourself, and the second is a native dependency of its own, which is where the undefined symbol build error comes from. And because the library ships native code, a bare JavaScript install is not enough: the podspec has to be installed into the iOS project, and the two troubleshooting entries are about the Xcode build rather than about JavaScript.

The repository also carries the tooling a maintained library needs: eslint, a circular dependency check that runs both dpdm and madge over the source, TypeScript checks for the library and the example, a lefthook.yml for git hooks, a turbo.json, and a make-readme.sh script for generating the readme from the documentation.

Where this library is the wrong choice

There are several cases where reaching for this library will cost you more than it gives.

The first is maintenance risk, and it is the dominant one. The author has said publicly that they are not doing open source work for the time being, and that the library is in maintenance mode. If your app depends on a native iOS component, you are depending on something that has no forward maintenance commitment, and the fact that the last release was in September 2025 while the repository still takes commits is a distinction without much comfort.

The second is the documentation. The readme states plainly that the documentation is incomplete, with TBA sections, that some links point to a placeholder, and that some images are broken. It also says the documentation and examples are currently being rewritten, and points at a work in progress TypeScript rewrite of the examples in the example directory. Adopting a native component whose API you have to discover by reading the source is a legitimate choice, but it is a real cost, and it is bigger here than it would be for an actively maintained library.

The third is that this is iOS only. The description and the readme are explicit about UIMenu and iOS 13/14+. If your application ships on Android as well, the context menu behaviour on the two platforms will not match, and you are back to a custom implementation for one of them.

The fourth is version 3 as a rewrite. If you are on version 2.x, moving to 3.x means a new implementation, a new peer dependency on react-native-ios-utilities 5.x, and a compatibility layer for the old architecture. And 2.x and below are no longer supported at all, so a stuck 2.x user has a genuine decision to make between a fork and a migration.

The fifth is whether you need the native menu at all. If the interaction you want is a simple list of actions on long press, a React Native implementation of a menu will do the same job, animate the way you want, work on both platforms, and carry no native build risk. What you give up is the exact system look and the auxiliary preview behaviour, which is the entire point of the library.

What the auxiliary preview actually adds

Since the preview is the feature that justifies the dependency, it is worth being precise about what the type system says about it.

The documentation index shows the preview configuration living in MenuPreviewConfig.ts, with a ContextMenuInteractionCommitStyle string union, a MenuPreviewSize union and a MenuPreviewType union. There is a MenuAuxiliaryPreviewBaseTransitionConfig object type and a MenuAuxiliaryPreviewTransitionConfig union type, and a mixed union type called MenuAuxiliaryPreviewTransitionEntranceDelay.

Two things follow from that naming. The preview has a transition, and the transition can be configured at a level of detail that includes a delay before the entrance animation, which is the kind of control you need when the preview is a live rendered element rather than a static image. And there is an explicit commit style, which suggests the interaction has a defined moment where the selection is committed, which matters when the preview itself is interactive rather than decorative.

That last point is where the library earns its keep. A preview that shows a live view, laid out as the item would appear, and where the user can interact with it before committing, is a distinctly iOS interaction, and reproducing it in JavaScript means reimplementing both the layout and the gesture handling. The auxiliary preview is marked as experimental in the documentation index, so the API around it is the part most likely to move.

The menu items themselves are configured through the MenuConfig family of types, and ImageItemConfig shows that image items can come from resolved asset sources, rectangles, gradients or system images, which is how you get an icon into a menu entry without shipping your own artwork pipeline.

Editorial conclusion

Adopt react-native-ios-context-menu if you are building an iOS React Native app that needs the real UIMenu, especially the auxiliary preview, and you are willing to depend on a library its author has placed in maintenance mode. Skip it if you need long term upstream fixes, since the readme says the author is no longer doing open source work for the time being. Verify first that your React Native version matches the architecture your build uses, that the peer dependencies on react-native-ios-utilities and ContextMenuAuxiliaryPreview are satisfied, and that the documentation gap does not hide the API you need.

Frequently asked questions

Official sources

1. dominicstop/react-native-ios-context-menu on GitHub
2. Issues
3. License: MIT
4. README
5. Releases