@exodus/react-native-menu

iOS14+ UIMenu components for react-native. Falls back to ActionSheet for versions below iOS14.

| iOS 14+ | iOS 13 | | ------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | | |

Installation

via npm:

npm install @exodus/react-native-menu

via yarn:

yarn add @exodus/react-native-menu

Installing on iOS with React Native 0.63 and above

There is an issue(https://github.com/facebook/react-native/issues/29246) causing projects with this module to fail on build on React Native 0.63 and above. This issue may be fixed in future versions of react native. As a work around, look for lines in [YourPrject].xcodeproj under LIBRARY_SEARCH_PATHS with "\"$(TOOLCHAIN_DIR)/usr/lib/swift-5.0/$(PLATFORM_NAME)\"", and change swift-5.0 to swift-5.3.

Linking

The package is automatically linked when building the app. All you need to do is:

npx pod-install

Usage

import { MenuView, MenuComponentRef } from "@exodus/react-native-menu";

const App = () => {
  const menuRef = useRef < MenuComponentRef > null;
  return (
    <View style={styles.container}>
      <MenuView
        ref={menuRef}
        title="Menu Title"
        onPressAction={({ nativeEvent }) => {
          console.warn(JSON.stringify(nativeEvent));
        }}
        actions={[
          {
            id: "add",
            title: "Add",
            titleColor: "#2367A2",
            image: "plus",
            imageColor: "#2367A2",
            subactions: [
              {
                id: "nested1",
                title: "Nested action",
                titleColor: "rgba(250,180,100,0.5)",
                subtitle: "State is mixed",
                image: "heart.fill",
                imageColor: "rgba(100,200,250,0.3)",
                state: "mixed",
              },
              {
                id: "nestedDestructive",
                title: "Destructive Action",
                attributes: {
                  destructive: true,
                },
                image: "trash",
              },
            ],
          },
          {
            id: "share",
            title: "Share Action",
            titleColor: "#46F289",
            subtitle: "Share action on SNS",
            image: "square.and.arrow.up",
            imageColor: "#46F289",
            state: "on",
          },
          {
            id: "destructive",
            title: "Destructive Action",
            attributes: {
              destructive: true,
            },
            image: "trash",
          },
        ]}
        shouldOpenOnLongPress={false}
      >
        <View style={styles.button}>
          <Text style={styles.buttonText}>Test</Text>
        </View>
      </MenuView>
    </View>
  );
};

Declarative usage

It's also possible to obtain the action is a more React-ish, declarative fashion. Refer to the react-to-imperative package, and see an example here.

Reference

Props

title (iOS only)

The title of the menu.

| Type | Required | | ------ | -------- | | string | Yes |

shouldOpenOnLongPress

Boolean determining if menu should open after long press or on normal press

| Type | Required | | ------- | -------- | | boolean | No |

actions

Actions to be displayed in the menu.

| Type | Required | | ------------ | -------- | | MenuAction[] | Yes |

themeVariant (iOS only)

String to override theme of the menu. If you want to control theme universally across your app, see this package.

| Type | Required | | --------------------- | -------- | | enum('light', 'dark') | No |

MenuAction

Object representing Menu Action.

export type MenuAction = {
  /**
   * Identifier of the menu action.
   * The value set in this id will be returned when menu is selected.
   */
  id?: string;
  /**
   * The action's title.
   */
  title: string;
  /**
   * (iOS14+ only)
   * An elaborated title that explains the purpose of the action.
   * @platform iOS
   */
  subtitle?: string;
  /**
   * The attributes indicating the style of the action.
   */
  attributes?: MenuAttributes;
  /**
   * (iOS14+ only)
   * The state of the action.
   * @platform iOS
   */
  state?: MenuState;
  /**
   * (iOS13+ only)
   * - The action's image.
   * - Allows icon name included in SF Symbol
   * @example
   * image="plus"
   */
  image?: string;
  /**
   * (iOS13+ only)
   * - The action's image color.
   */
  imageColor?: number | ColorValue;
  /**
   * (iOS14+ only)
   * - Actions to be displayed in the sub menu
   */
  subactions?: MenuAction[];
};

MenuAttributes

The attributes indicating the style of the action.

type MenuAttributes = {
  /**
   * An attribute indicating the destructive style.
   */
  destructive?: boolean;
  /**
   * An attribute indicating the disabled style.
   */
  disabled?: boolean;
  /**
   * An attribute indicating the hidden style.
   */
  hidden?: boolean;
};

MenuState

The state of the action.

/**
 * The state of the action.
 * - off: A constant indicating the menu element is in the "off" state.
 * - on: A constant indicating the menu element is in the "on" state.
 * - mixed: A constant indicating the menu element is in the "mixed" state.
 */
type MenuState = "off" | "on" | "mixed";

onPressAction

Callback function that will be called when selecting a menu item. It will contain id of the given action.

| Type | Required | | ----------------------- | -------- | | ({nativeEvent}) => void | No |

Events

onCloseMenu

Callback function that will be called when the menu is dismissed. This event fires at the start of the dismissal, before any animations complete.

| Type | Required | | ---------- | -------- | | () => void | No |

onOpenMenu

Callback function that will be called when the menu is opened. This event fires right before the menu is displayed.

| Type | Required | | ---------- | -------- | | () => void | No |

Example usage:

<MenuView
  onOpenMenu={() => {
    console.log("Menu was opened");
  }}
  onCloseMenu={() => {
    console.log("Menu was closed");
  }}
>
  <View>
    <Text>Open Menu</Text>
  </View>
</MenuView>

Testing with Jest

In some cases, you might want to mock the package to test your components. You can do this by using the jest.mock function.

import type { MenuComponentProps } from "@exodus/react-native-menu";

jest.mock("@exodus/react-native-menu", () => ({
  MenuView: jest.fn((props: MenuComponentProps) => {
    const React = require("react");

    class MockMenuView extends React.Component {
      render() {
        return React.createElement(
          "View",
          { testID: props.testID },
          props.actions.map((action) =>
            React.createElement("Button", {
              key: action.id,
              title: action.title,
              onPress: () => {
                if (action.id && props?.onPressAction) {
                  props.onPressAction({ nativeEvent: { event: action.id } });
                }
              },
              testID: action.id,
            })
          ),
          this.props.children
        );
      }
    }

    return React.createElement(MockMenuView, props);
  }),
}));

Contributing

See the contributing guide to learn how to contribute to the repository and the development workflow.

License

MIT