Skip to content

Live photo

@symbiote-native/live-photo wraps expo-live-photo, so every SymbioteNative adapter can show a Live Photo, not just React. On Android the view renders nothing.

Terminal window
npm install @symbiote-native/live-photo

Scaffolding or extending a SymbioteNative app? npx @symbiote-native/cli new --live-photo (or add --live-photo in an existing app) installs and wires this for you.

The photo and the video must come from one unaltered live photo file, the pairing lives in their metadata. Keep the handle of the view to start and stop playback.

import { useRef } from 'react';
import { LivePhotoView, type ILivePhotoViewHandle } from '@symbiote-native/live-photo/react';
const handle = useRef<ILivePhotoViewHandle>(null);
<LivePhotoView
ref={handle}
style={{ width: 300, height: 400 }}
source={{ photoUri, pairedVideoUri }}
onLoadError={error => console.warn(error.message)}
/>;
<button title="Play" onPress={() => handle.current?.startPlayback('hint')} />;
Adapter How
React ref gets an ILivePhotoViewHandle
Solid ref={handle => ...} gets the handle
Vue a template ref, startPlayback/stopPlayback are exposed
Svelte bind:this, the component exports both functions
Angular @ViewChild(LivePhotoView), both are methods
Prop Description
source { photoUri, pairedVideoUri }
isMuted true by default
contentFit contain (default) or cover
useDefaultGestureRecognizer Press and hold plays, true by default
onLoadStart Loading began
onPreviewPhotoLoad The preview photo is loaded
onLoadComplete Ready to play
onLoadError Gets { message }
onPlaybackStart / onPlaybackStop Playback state changed

Plus style, testID, nativeID, onLayout and the accessibility and responder props every View takes.

  • iOS only. Off iOS the view renders nothing, with a warning in development, and the handle throws UnavailabilityError. Check Platform.OS before you render it.
  • A Live Photo is two files. The still photo and the paired video, and they must stay a pair: the pairing lives in their metadata, so editing or recompressing either one breaks it.
  • Playback style. startPlayback() plays the full clip, startPlayback('hint') plays the short preview you see when you press a photo in the Photos app.
  • Muted by default. isMuted is true, unmute it when the sound is part of the content.
  • Press and hold plays while useDefaultGestureRecognizer is true. Turn it off and call startPlayback yourself if the photo has its own gestures.

Where do I get photoUri and pairedVideoUri? From the picker. With @symbiote-native/image-picker, ask for mediaTypes: ['livePhotos'] and read assets[0].uri for the photo and assets[0].pairedVideoAsset?.uri for the video. A photo stored in iCloud and not on the phone needs the picker’s shouldDownloadFromNetwork option, or the pair may not arrive.

I cannot find a Live Photo in the Simulator. Live Photos are made by the iPhone camera. The Simulator cannot take one, so test with a real device and a photo that has the Live badge.

onLoadError fires, or the photo shows but never plays. The two files do not belong together. Pass the two URIs that came out of one pick, not a photo from one place and a video from another, and do not run either through an editor or an image manipulator first.

Can I get the pair from the media library? The shared-object API of @symbiote-native/media-library resolves the paired video of a Live Photo, but resolving the still half as a local file was reported to throw for some assets, and getAssetInfoAsync crashed on Live Photos on iOS in SDK 56 before a fix. The picker is the safer way to get a ready pair.

It plays without sound. isMuted defaults to true. Pass isMuted={false}.

How do I start playback from a button? Keep the handle and call startPlayback('full') or startPlayback('hint'), and stopPlayback() to end it. onPlaybackStart and onPlaybackStop tell you when the state changes.

Does it work on Android? No, Live Photo is an Apple format. The view renders nothing there.

Sources:

expo-live-photo’s JS is hand-ported into this package’s core/. A native Expo view keeps its functions on its module’s view prototypes and native finds the view by its native tag, so the engine’s defineExpoViewMethods makes that call and the core createLivePhotoViewHandle(getNode) wraps it. Each adapter only hands over its host node: React and Vue a function ref in the descriptor props, Solid the same through spread, Svelte bind:this, Angular the outlet’s root node. The handle is a ref in React and Solid, expose in Vue, exported functions in Svelte and methods in Angular.

The package declares only ios.upstreamPackage in native-link.json, since upstream has no Android folder and no config plugin. The native code is never vendored: expo-modules-autolinking resolves it from node_modules (see the native setup guide).