Skip to content

About

A performant, fully customizable long-press context menu for React Native.

Topics

Resources

Code of conduct

Contributing

Stars

20 stars

Watchers

2 watching

Forks

Latest commit

ย 

History

69 Commits

Folders and files

NameName
Last commit message
Last commit date
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 
ย 

Repository files navigation

react-native-peek-menu

Add interactive context menus and rich previews to any React Native component.

CI platforms bundle size

Holding messages in a chat over a blurred screen: a link opens a live preview of the web page, and a long message lifts above the screen, each with a menu of Reply, Copy, Edit, Pin, Forward, Delete and Select Holding a photo in a two-column gallery over a blurred screen opens it whole as a large preview, with a menu of Add to Favorites, Share, Add to Album, Download and Delete

Key features

  • Fully customizable: the menu, the preview and the backdrop
  • Smooth animations
  • No native code
  • Always stays on screen
  • Keyboard-aware behavior
  • Opens on hold, tap or double tap
  • RTL support
  • Portrait and landscape support

Table of Contents

Installation

Works with Expo and React Native CLI apps on the New Architecture.

Peer dependencies:

  • react >= 19
  • react-native >= 0.86
  • react-native-reanimated >= 4.7
  • react-native-worklets >= 0.13
  • react-native-gesture-handler >= 3.3

First install and set up the peer dependencies by following their official guides:

Then install the library:

# Expo
npx expo install react-native-peek-menu

# React Native CLI
npm install react-native-peek-menu

Quick start

Wrap your app in PeekMenuProvider, then wrap anything that should open a menu in PeekMenu.

import { Text, View } from 'react-native';
import { PeekMenu, PeekMenuProvider } from 'react-native-peek-menu';

export default function App() {
  return (
    <PeekMenuProvider>
      <PeekMenu
        items={[
          { title: 'Reply', onPress: reply },
          { title: 'Copy', onPress: copy },
          { title: 'Delete', destructive: true, onPress: remove },
        ]}
      >
        <View>
          <Text>Hold me</Text>
        </View>
      </PeekMenu>
    </PeekMenuProvider>
  );
}

Recipes

Safe area, header and input bar

Pass the safe area so the menu keeps clear of the notch and the home indicator.

If a header, an input bar or a tab bar covers the top or bottom of the screen, even a translucent one, pass how much of it they cover as clipInsets. The menu opens between them, and content partly hidden under them opens and closes smoothly.

import { PeekMenu, PeekMenuProvider } from 'react-native-peek-menu';
import { useSafeAreaInsets } from 'react-native-safe-area-context';

function App() {
  const insets = useSafeAreaInsets();

  return (
    <PeekMenuProvider safeAreaInsets={insets}>
      <Chat />
    </PeekMenuProvider>
  );
}

function ChatMessage({ message, headerHeight, inputBarHeight }: ChatMessageProps) {
  return (
    <PeekMenu items={items} clipInsets={{ top: headerHeight, bottom: inputBarHeight }}>
      <Bubble message={message} />
    </PeekMenu>
  );
}

Above modals

To open menus above modals on iOS, pass FullWindowOverlay from react-native-screens.

import { Platform } from 'react-native';
import { PeekMenuProvider } from 'react-native-peek-menu';
import { FullWindowOverlay } from 'react-native-screens';

function App() {
  return (
    <PeekMenuProvider overlayContainer={Platform.OS === 'ios' ? FullWindowOverlay : undefined}>
      <Navigation />
    </PeekMenuProvider>
  );
}

On Android, wrap the content of a Modal in its own PeekMenuProvider.

A custom backdrop

Replace the dimmed layer behind the menu with your own, like a blur that fades in and out with the menu.

import { BlurView } from 'expo-blur';
import { StyleSheet } from 'react-native';
import { PeekMenuProvider, type PeekMenuBackdropProps } from 'react-native-peek-menu';
import Animated, { useAnimatedProps } from 'react-native-reanimated';

const AnimatedBlurView = Animated.createAnimatedComponent(BlurView);

function BlurBackdrop({ progress }: PeekMenuBackdropProps) {
  const animatedProps = useAnimatedProps(() => ({
    intensity: Math.min(progress.get(), 1) * 40,
  }));

  return (
    <AnimatedBlurView tint="dark" animatedProps={animatedProps} style={StyleSheet.absoluteFill} />
  );
}

function App() {
  return (
    <PeekMenuProvider renderBackdrop={(props) => <BlurBackdrop {...props} />}>
      <Chat />
    </PeekMenuProvider>
  );
}

On Android, BlurView shows a tinted layer instead of a blur unless you set up blurTarget, as described in the expo-blur docs.

A custom menu

Restyle the list to match your app. Set renderMenu on PeekMenuProvider for every menu, or on a PeekMenu for one. Rows call onItemPress, which closes the menu and runs the item's onPress.

import { Pressable, StyleSheet, Text, View } from 'react-native';
import { PeekMenuProvider, type PeekMenuRenderProps } from 'react-native-peek-menu';

function BrandMenu({ items, onItemPress }: PeekMenuRenderProps) {
  return (
    <View style={styles.menu}>
      {items.map((item) => (
        <Pressable key={item.title} onPress={() => onItemPress(item)} style={styles.row}>
          <Text style={[styles.title, item.destructive && styles.destructive]}>{item.title}</Text>
        </Pressable>
      ))}
    </View>
  );
}

function App() {
  return (
    <PeekMenuProvider renderMenu={(props) => <BrandMenu {...props} />}>
      <Chat />
    </PeekMenuProvider>
  );
}

const styles = StyleSheet.create({
  menu: {
    width: 240,
    maxWidth: '100%',
    borderRadius: 20,
    backgroundColor: '#1E1B4B',
  },
  row: {
    padding: 14,
  },
  title: {
    color: '#EEF2FF',
  },
  destructive: {
    color: '#FCA5A5',
  },
});

A custom menu needs a width, and maxWidth: '100%' keeps it on small screens.

Anything as a menu

renderMenu can show any element instead of the list, like a row of reactions. Call close when it's done and pass it the action to run.

import { Pressable, StyleSheet, Text, View } from 'react-native';
import { PeekMenu } from 'react-native-peek-menu';

const REACTIONS = ['โค๏ธ', '๐Ÿ‘', '๐Ÿ˜‚', '๐Ÿ˜ฎ', '๐Ÿ˜ข'];

function Reactions({ onSelect }: { onSelect: (emoji: string) => void }) {
  return (
    <View style={styles.reactions}>
      {REACTIONS.map((emoji) => (
        <Pressable key={emoji} onPress={() => onSelect(emoji)} style={styles.reaction}>
          <Text style={styles.emoji}>{emoji}</Text>
        </Pressable>
      ))}
    </View>
  );
}

function ChatMessage({ message }: { message: Message }) {
  return (
    <PeekMenu
      renderMenu={({ close }) => (
        <Reactions onSelect={(emoji) => close(() => react(message.id, emoji))} />
      )}
    >
      <Bubble message={message} />
    </PeekMenu>
  );
}

const styles = StyleSheet.create({
  reactions: {
    flexDirection: 'row',
    gap: 4,
    padding: 6,
    borderRadius: 28,
    backgroundColor: '#FFF',
  },
  reaction: {
    padding: 6,
  },
  emoji: {
    fontSize: 28,
  },
});

A custom preview

preview shows something else in place of the content while the menu is open, like the whole photo behind a square thumbnail. The preview takes its own size and opens from the content, so set its width or height when it needs one: width: '100%' makes it as wide as the screen allows, and a wider one is scaled down to fit.

import { Image } from 'react-native';
import { PeekMenu } from 'react-native-peek-menu';

function GalleryPhoto({ photo }: { photo: Photo }) {
  return (
    <PeekMenu
      items={items}
      preview={
        <Image
          source={{ uri: photo.uri }}
          style={{ width: '100%', aspectRatio: photo.width / photo.height, borderRadius: 16 }}
        />
      }
    >
      <Image source={{ uri: photo.uri }} style={{ width: 120, height: 120 }} />
    </PeekMenu>
  );
}

Pass a function to get isOpened, which turns true once the menu has finished opening, and use it however you need. For example, show heavy content like a WebView only then, in a box of the same size, so it doesn't slow down the opening.

import { View } from 'react-native';
import { PeekMenu } from 'react-native-peek-menu';
import { WebView } from 'react-native-webview';

function LinkMessage({ url }: { url: string }) {
  return (
    <PeekMenu
      items={items}
      preview={({ isOpened }) => (
        <View style={{ width: '100%', height: 420 }}>
          {isOpened && <WebView source={{ uri: url }} style={{ flex: 1 }} />}
        </View>
      )}
    >
      <LinkBubble url={url} />
    </PeekMenu>
  );
}

API

PeekMenuProviderProps

Prop Type Default Description
children ReactNode required The part of the app that can open menus.
safeAreaInsets PeekMenuInsets All 0 Space to keep clear on each side.
colorScheme 'system' | 'light' | 'dark' 'system' The theme of the default menu. 'system' follows the device.
backdropColor string 'rgba(10, 14, 20, 0.5)' Color of the layer behind the menu.
renderBackdrop (props: PeekMenuBackdropProps) => ReactNode Replaces that layer, and backdropColor is ignored.
renderMenu (props: PeekMenuRenderProps) => ReactNode Renders every menu. A PeekMenu can override it with its own.
overlayContainer ComponentType<{ children: ReactNode }> Shows the open menu inside this component, like FullWindowOverlay to keep it above modals on iOS.

PeekMenuProps

A PeekMenu needs items, renderMenu, or both.

Prop Type Default Description
children ReactNode required The content that opens the menu, held by default.
items PeekMenuItem[] [] The rows, read when the menu opens. An empty list stops it from opening, unless there's a renderMenu.
renderMenu (props: PeekMenuRenderProps) => ReactNode Renders this menu instead of the default list.
preview ReactNode | ((props: PeekMenuPreviewProps) => ReactNode) Shown instead of children while the menu is open. It takes its own size, so give it a width or height if needed. As a function, it gets isOpened.
placement 'top' | 'bottom' 'bottom' The side of the content the menu opens on.
alignment 'auto' | 'start' | 'center' | 'end' 'auto' Where the menu lines up with the content. 'start' and 'end' follow the layout direction.
clipInsets { top?: number; bottom?: number } How much of the top and bottom is covered by something, opaque or translucent, like a header or an input bar.
activateOn 'hold' | 'tap' | 'double-tap' 'hold' How the content opens the menu. With a tap, the content shouldn't handle presses itself.
holdDuration number 300 How long to hold, in milliseconds. Only used with activateOn set to 'hold'.
disabled boolean false Stops the content from opening the menu.
style StyleProp<ViewStyle> Layout of the wrapper, like margin or alignSelf.
onOpen () => void Called when the menu starts to open.
onClose () => void Called once the menu has finished closing.

PeekMenuItem

Field Type Default Description
title string required Text shown in the row.
onPress () => void required Called when the row is pressed, as the menu starts to close.
destructive boolean false Shows the title in red, for actions like Delete.
disabled boolean false Shows the row dimmed and stops it from being pressed.
icon ReactNode Any element to show beside the title. Its color isn't changed by destructive or the dark theme.
iconPosition 'left' | 'right' 'right' The side of the row the icon sits on.

PeekMenuRenderProps

What renderMenu receives.

Field Type Description
items PeekMenuItem[] The rows of the open menu, empty if it has none.
onItemPress (item: PeekMenuItem) => void Closes the menu and calls the item's onPress. Skips disabled items.
close (action?: () => void) => void Closes the menu and runs action once.
progress SharedValue<number> From 0 when closed to 1 when open. The open spring can pass 1 slightly.

PeekMenuBackdropProps

What renderBackdrop receives.

Field Type Description
progress SharedValue<number> From 0 when closed to 1 when open. The open spring can pass 1 slightly.

PeekMenuPreviewProps

What preview receives when it's a function.

Field Type Description
isOpened boolean Whether the menu has finished opening. It stays true while the menu closes.

License

MIT

About

A performant, fully customizable long-press context menu for React Native.

Topics

Resources

Code of conduct

Contributing

Stars

20 stars

Watchers

2 watching

Forks

Releases

Packages

Used by

Contributors

Languages