API

MenuProvider

It provides methods to handle popup menus imperatively. The same methods are exposed to the context property menuActions. This can be retrieved by HOC withMenuContext that adds ctx property to your component. Then simply call props.ctx.menuActions.method().

Note: It is important that <MenuProvider /> is on the top of the component hierarchy (e.g. ScrollView should be inside of MenuProvider) and wraps all <Menu /> components. This is needed in order to solve z-index issues. The only known exception is when you use Modal - you need to place (additional) 'MenuProvider' inside of 'Modal' (see our ModalExample) Note: MenuProvider was formerly named MenuContext which is now deprecated.

Methods, menuActions context

Method Name	Arguments	Notes
openMenu	name	Opens menu by name. Returns promise
toggleMenu	name	Toggle menu by name. Returns promise
closeMenu		Closes currently opened menu. Returns promise
isMenuOpen		Returns true if any menu is open

Properties

Option	Type	Opt/Required	Default	Note
style	Style	Optional		Style of wrapping View component. Same as customStyles.menuProviderWrapper but when both are present result style is a merge where this style has higher precedence.
customStyles	Object	Optional		Object defining wrapper, touchable and text styles
backHandler	boolean|Function	Optional	false	Whether to close the menu when the back button is pressed or custom back button handler if a function is passed (RN >= 0.44 is required)
skipInstanceCheck	boolean	Optional	false	Normally your application should have only one menu provider (with exception as discussed above). If you really need more instances, set skipInstanceCheck to true to disable the check (and following warning message)
SafeAreaComponent	Component	Optional	View	Component to use for safe area wrapper. Can be set to SafeAreaView from React Native to restore the old behavior or any 3rd component like react-native-safe-area-context

Custom styles

To style <MenuProvider /> and backdrop component you can pass customStyles object prop with following keys:

Object key	Type	Notes
menuProviderWrapper	Style	Style of wrapping View component (formerly menuContextWrapper)
backdrop	Style	Backdrop View style
safeArea	Style	Safe area wrapper style. When not provided, default padding of 30 is applied to top and bottom

Note: Style type is any valid RN style parameter. Note: In addition to these styles we add also {flex:1}. You can disable it by e.g. style={{flex:0}}.

See more in custom styling example.

Handling of back button

To handle the back button you can pass backHandler prop with the following possible values:

Value	Description
false	No handling of back button press
true	The menu will be closed
Function	The function will be called with MenuProvider instance as the first parameter. The function needs to return true to prevent application exit (or bubbling if there are other listeners registered). Read BackHandler documentation for more information.

See more in custom close on back example.

Menu

Root menu component defining menu name and providing menu events.

Methods

Method Name	Arguments	Notes
open		Opens menu. Returns promise
isOpen		Returns wheter the menu is open or not
close		Closes menu. Returns promise

Properties

Option	Type	Opt/Required	Default	Note
name	String	Optional	auto-generated	Unique name of menu
opened	Boolean	Optional		Declaratively states if menu is opened. When this prop is provided, menu is controlled and imperative API won't work.
renderer	Function	Optional	ContextMenu	Defines position, animation and basic menu styles. See renderers section for more details
rendererProps	Object	Optional		Additional props which will be passed to the renderer

Events

Event Name	Arguments	Notes
onSelect	optionValue	Triggered when menu option is selected. When event handler returns false, the popup menu remains open
onOpen		Triggered when menu is opened
onClose		Triggered when menu is closed
onBackdropPress		Triggered when user press backdrop (outside of the opened menu)

Static Properties

Property name	Type	Opt/Required	Default	Note
debug	Boolean	Optional	false	This property enables debug logs

Static Functions

Function name	Arguments	Returns	Note
setDefaultRenderer	Function		Sets new default renderer. See renderers section for more details
setDefaultRendererProps	Object		Sets new default renderer props

MenuTrigger

It defines position where the popup menu will be rendered. Menu can by opened by clicking on <MenuTrigger /> or by calling context methods.

Note: It is necessary that <MenuTrigger /> is a direct child of <Menu />.

Properties

Option	Type	Opt/Required	Default	Note
disabled	Boolean	Optional	false	Indicates if trigger can be pressed
children	Elements	Optional		React elements to render as menu trigger. Exclusive with text property
text	String	Optional		Text to be rendered. When this prop is provided, trigger's children won't be rendered
customStyles	Object	Optional		Object defining wrapper, touchable and text styles
triggerOnLongPress	Boolean	Optional	false	If true, menu will trigger onLongPress instead of onPress
testID	String	Optional		Used for e2e testing to get Touchable element

Events

Event Name	Arguments	Notes
onPress		Triggered when trigger is pressed (or longpressed depending on triggerOnLongPress)
onAlternativeAction		Triggered when trigger is longpressed (or pressed depending on triggerOnLongPress)

Custom styles

To style <MenuTrigger /> component you can pass customStyles object prop with following keys:

Object key	Type	Notes
triggerOuterWrapper	Style	Style of outer View component
triggerWrapper	Style	Style of inner View component (can be overriden by style prop)
triggerText	Style	Style of Text component (used when text shorthand option is defined)
TriggerTouchableComponent	Component	Touchable component of trigger. Default value is TouchableHighlight for iOS and TouchableNativeFeedvack for Android
triggerTouchable	Object	Properties passed to the touchable component (e.g. activeOpacity, underlayColor for TouchableHighlight)

Note: Style type is any valid RN style parameter.

See more in custom styling example and touchable example.

MenuOptions

This component wrapps all menu options.

Note: It is necessary that <MenuOptions /> is a direct child of <Menu />.

Properties

Option	Type	Opt/Required	Default	Note
optionsContainerStyle	Style	Optional		Custom styles for options container. Note: this option is deprecated, use customStyles option instead
renderOptionsContainer	Func	Optional	options => options	Custom render function for <MenuOptions />. It takes options component as argument and returns component. E.g.: options => <SomeCustomContainer>{options}</SomeCustomContainer> (Deprecated)
customStyles	Object	Optional		Object defining wrapper, touchable and text styles

Custom styles

To style <MenuOptions /> and it's <MenuOption /> components you can pass customStyles object prop with following keys:

Object key	Type	Notes
optionsWrapper	Style	Style of wrapping MenuOptions component (can be overriden by style prop)
optionsContainer	Style	Style passed to the menu renderer (e.g. Animated.View)
optionWrapper	Style	Style of View component wrapping single option
optionText	Style	Style of Text component (when text shorthand option is defined)
OptionTouchableComponent	Component	Touchable component of option. Default value is TouchableHighlight for iOS and TouchableNativeFeedvack for Android
optionTouchable	Object	Properties passed to the touchable component (e.g. activeOpacity, underlayColor for TouchableHighlight)

Note: optionWrapper, optionTouchable and optionText styles of particular menu option can be overriden by customStyles prop of <MenuOption /> component.

Note: In order to change customStyles dynamically, it is required that no child of MenuOptions stops the update (e.g. shouldComponentUpdate returning false).

Note: Style type is any valid RN style parameter.

See more in custom styling example and touchable example.

MenuOption

Wrapper component of menu option.

Properties

Option	Type	Opt/Required	Default	Note
value	Any	Optional		Value of option
children	Elements	Optional		React elements to render as menu option. Exclusive with text property
text	String	Optional		Text to be rendered. When this prop is provided, option's children won't be rendered
disabled	Boolean	Optional	false	Indicates if option can be pressed
disableTouchable	Boolean	Optional	false	Disables Touchable wrapper (no on press effect and no onSelect execution) Note: Alternatively you don't have to use MenuOption at all if you want render something "non-selectable" in the menu (e.g. divider)
customStyles	Object	Optional		Object defining wrapper, touchable and text styles
testID	String	Optional		Used for e2e testing to get Touchable element. If disableTouchable=true, it is not available

Events

Event Name	Arguments	Notes
onSelect		Triggered when option is selected. When event handler returns false, the popup menu remains open. Note: If this event handler is defined, it suppress onSelect handler of <Menu />

Custom styles

To style <MenuOption /> component you can pass customStyles object prop with following keys:

Object key	Type	Notes
optionWrapper	Style	Style of wrapping View component.
optionText	Style	Style of Text component (when text shorthand option is defined)
OptionTouchableComponent	Component	Touchable component of option. Default value is TouchableHighlight for iOS and TouchableNativeFeedvack for Android
optionTouchable	Object	Properties passed to the touchable component (e.g. activeOpacity, underlayColor for TouchableHighlight)

Note: Style type is any valid RN style parameter.

See more in custom styling example and touchable example.

Renderers

Renderers are react components which wraps MenuOptions and are responsible for menu position and animation. It is possible to extend menu and use custom renderer (see implementation of existing renderers or extension guide). All renderers can be found in renderers module.

Note: Renderers can be customized by props which can be passed through rendererProps option or setDefaultRendererProps static method.

ContextMenu (default)

Opens (animated) context menu over the trigger position. The ContextMenu.computePosition exports function for position calculation in case you would like to implement your own renderer (without special position calculation).

NotAnimatedContextMenu

Same as ContextMenu but without any animation.

SlideInMenu

Slides in the menu from the bottom of the screen.

Popover

Displays menu as a popover. Popover can be customized by following props:

Option	Type	Opt/Required	Default	Note
placement	String	Optional	auto	Position of popover to the menu trigger - top | right | bottom | left | auto
preferredPlacement	String	Optional	top	Preferred placement of popover - top | right | bottom | left. Applicable when placement is set to auto
anchorStyle	Style	Optional		Styles passed to popover anchor component
openAnimationDuration	Number	Optional	225	Duration of animation to show the popover
closeAnimationDuration	Number	Optional	195	Duration of animation to hide the popover