Native iOS context menu with peek preview. Long-pressing a wrapped view shows a UIContextMenuInteraction with a peek preview (a full-size image, or an external link card that can morph into an in-app browser) and an action menu. Android and web fall through to a passthrough View.

Installation

npm install @bsky.app/peek-menu

Note: The iOS native side shares SDImageCache.shared with expo-image via SDWebImage ~> 5.21.0. Your app must have a compatible SDWebImage version installed (expo-image provides this).

Usage

Declarative, compound-component API. Root collects children tagged as Trigger and Menu, serializes the menu items, and renders a single native view.

import * as PeekMenu from '@bsky.app/peek-menu'
;<PeekMenu.Root>
  <PeekMenu.Trigger
    preview={{
      type: 'image',
      uri: fullsizeUrl,
      thumbUri: thumbUrl,
      aspectRatio: 1.5,
    }}
    borderRadius={12}>
    {children}
  </PeekMenu.Trigger>
  <PeekMenu.Menu>
    <PeekMenu.MenuItem id="save" onSelect={handleSave}>
      <PeekMenu.MenuItemIcon icon={SaveIcon} />
      <PeekMenu.MenuItemText>Save image</PeekMenu.MenuItemText>
    </PeekMenu.MenuItem>
  </PeekMenu.Menu>
</PeekMenu.Root>

Trigger, Menu, MenuItem, MenuItemIcon, and MenuItemText are sentinel components — they render nothing. Root walks the children tree at render time, extracts their props, and passes serialized data to the native view.

Props

Trigger

preview?: PreviewContent — what to show during peek. image and link are implemented; video is typed but will fall back to no preview. The link variant carries its own useInAppBrowser / browserToolbarColor / browserControlsColor options (see Preview types and Link previews).
borderRadius?: number — corner radius of the thumbnail. Used in the native targeted-preview so the lift animation matches the clipping.
onPreviewPress?: () => void — fires when the user taps the expanded preview to commit into it (i.e. open the lightbox). Not called for a link preview when its useInAppBrowser is true — the native browser morph handles that tap.

MenuItem

id: string — stable identifier, sent back in the onItemPress event.
onSelect: () => void — called when this item is tapped.
destructive?: boolean — renders the item in red.
disabled?: boolean — greys the item out.

MenuItemIcon

icon: SvgIconMeta — any object with svgPaths: string[], svgViewBox: string, and svgStrokeWidth: number. Rendered natively via IconRenderer.

Icon compatibility

The SvgIconMeta type is intentionally minimal:

type SvgIconMeta = {
  svgPaths: string[]
  svgViewBox: string
  svgStrokeWidth: number
}

Any icon component that carries these three properties (e.g. those created with createSinglePathSVG) can be passed directly — TypeScript's structural typing handles the rest.

Preview types

type PreviewContent =
  | {type: 'image'; uri: string; thumbUri?: string; aspectRatio: number}
  | {type: 'video'; uri: string; poster?: string; aspectRatio: number} // not yet implemented
  | {
      type: 'link'
      url: string
      useInAppBrowser?: boolean
      browserToolbarColor?: string // hex, e.g. '#ffffff'
      browserControlsColor?: string // hex, e.g. '#0085ff'
    }

A link peek always previews the live page in an SFSafariViewController — the url is loaded natively, along with the optional browser tints (matching expo-web-browser's toolbarColor / controlsColor). useInAppBrowser only changes what tapping the peek does (see below).

Platform behavior

Platform	Behavior
iOS	Native `UIContextMenuInteraction` with peek preview and action menu
Android	Passthrough `View` wrapper (no context menu)
Web	Passthrough `View` wrapper (no context menu)

iOS native architecture

Image loading

ImagePreviewController shares SDWebImage's SDImageCache.shared and SDWebImageManager.shared with expo-image, so cache hits are free:

Memory cache hit on fullsize? Paint it immediately — zero latency.
Memory or disk cache hit on thumbnail? Paint the thumb as a placeholder, then async-load the fullsize. Thumbs are small enough that a sync disk read is acceptable.
No cache hit? Show nothing initially, async-load the fullsize.

For best results, prefetch the fullsize image into memory on press-in so it's ready by the time the peek animation starts:

<Pressable
  onPressIn={() => {
    requestIdleCallback(() => {
      Image.prefetch(fullsizeUri, 'memory')
    })
  }}>
  {children}
</Pressable>

This is the pattern used by social-app — Image.prefetch(url, 'memory') from expo-image writes into SDImageCache.shared, which the native preview controller reads from synchronously.

Link previews

The peek is always a live SFSafariViewController already loading the page. The useInAppBrowser option only changes what tapping the peek does:

useInAppBrowser: true — the tap commits via UIContextMenuInteractionCommitStyle.pop, then presents that same Safari instance in the commit completion so it morphs seamlessly to full-screen — Apple's documented peek-and-pop pattern for links. (.pop plays the animation but doesn't present the VC itself, so we present it, unanimated, once the morph has filled the screen.) Because the morph happens entirely natively, onPreviewPress is not fired in this mode.
useInAppBrowser: false (or omitted) — the tap just dismisses the peek and fires onPreviewPress, leaving navigation to the host app (e.g. Linking.openURL, or a consent dialog).

This split lets the host honor a user "open links in app" preference: pass it straight through as useInAppBrowser, and let onPreviewPress cover the off/unset cases. Pre-proxy the url on the JS side if your app rewrites outbound links — the native side opens it verbatim.

Note: because the peek loads the page on long-press regardless of the tap behavior, it does fetch the URL even when useInAppBrowser is off. That's the same as a Safari/Messages link peek.

Known limitations

Carousel clipping: When an image is inside a horizontal FlatList, the UIScrollView's clipsToBounds clips the peek lift animation and its shadow.
Android/web: No native implementation yet. Falls through to a plain View wrapper.
Video previews: Typed in PreviewContent but not implemented on the native side.