react-native-morph-card

react-native-morph-card

Native card-to-modal morph transition for React Native. Smoothly animates a card from a list into a fullscreen detail view, morphing size, position, and corner radius — then collapses back.

• Native animations on both platforms (UIKit UIViewPropertyAnimator / Android ValueAnimator)
• No JS-driven animation, no webview, no experimental flags
• Works with any navigation setup (React Navigation, expo-router, etc.)
• Supports React Native new architecture (Fabric)

Table of Contents

• Installation
• Usage
• API
  • <MorphCardSource>
  • <MorphCardTarget>
  • useMorphTarget
  • Imperative API
• Running the Example App
• Troubleshooting
• Contributing
• Roadmap
• License

Installation

npm install react-native-morph-card
# or
yarn add react-native-morph-card

iOS

cd ios && pod install

Android

No additional steps required.

Usage

Wrap your card content in MorphCardSource. On the detail screen, use MorphCardTarget where the card should land. Use useMorphTarget for easy collapse handling.

Important: MorphCardSource can wrap any React Native component (images, views, text, etc.). During the animation, the content is captured as a bitmap snapshot — but once the animation completes, the snapshot fades out and the source's children are automatically cloned into MorphCardTarget as live React components. The cloned children are rendered at the source card's original layout dimensions, so your component layout stays consistent. This means observable values (timers, animated values, live data) will update in real time after the transition finishes. If you use resizeMode, the bitmap is kept instead (native image scaling doesn't apply to React components).

import React from 'react';
import { View, Image, Text, Pressable } from 'react-native';
import {
  MorphCardSource,
  MorphCardTarget,
  useMorphTarget,
} from 'react-native-morph-card';

// ── List screen ──
const ListScreen = ({ navigation }) => {
  return (
    <MorphCardSource
      width={200}
      height={150}
      borderRadius={16}
      expandDuration={350}
      onPress={(sourceTag) => navigation.navigate('Detail', { sourceTag })}
    >
      <Image source={albumArt} style={{ width: 200, height: 150 }} />
    </MorphCardSource>
  );
};

// ── Detail screen ──
const DetailScreen = ({ route, navigation }) => {
  const { dismiss } = useMorphTarget({
    sourceTag: route.params.sourceTag,
    navigation,
  });

  return (
    <View style={{ flex: 1 }}>
      <MorphCardTarget
        sourceTag={route.params.sourceTag}
        width={'100%'}
        height={300}
        collapseDuration={200}
        borderRadius={0}
      />
      <Pressable onPress={dismiss}>
        <Text>Close</Text>
      </Pressable>
    </View>
  );
};

API

<MorphCardSource>

Wraps the card content on the list/grid screen. Captures a snapshot and drives the expand animation.

Prop	Type	Default	Description
width	DimensionValue	—	Card width
height	DimensionValue	—	Card height
borderRadius	number	0	Corner radius of the card
backgroundColor	string	—	Background color (enables "wrapper mode" where the background expands separately from the content)
duration	number	300	Default animation duration in ms (used for both expand and collapse if specific durations are not set)
expandDuration	number	—	Duration of the expand animation in ms. Overrides duration for expand.
resizeMode	'cover' | 'contain' | 'stretch'	'cover'	How the snapshot scales during animation. When set, the bitmap is kept after expand (no live children). Recommended when wrapping an <Image> — without it, the image may not scale properly during the animation.
rotations	number	0	Number of full 360° rotations during the expand animation
rotationEndAngle	number	0	Final rotation angle in degrees after expand (e.g. 45 to end tilted). Collapse reverses it back to 0
onPress	(sourceTag: number) => void	—	Called on tap with the native view tag. Use this to navigate to the detail screen.

<MorphCardTarget>

Placed on the detail screen where the card should land. Triggers the expand animation on mount. After the animation, the source's children are automatically cloned here as live React components.

Prop	Type	Default	Description
sourceTag	number	required	The source view tag from navigation params
width	DimensionValue	source width	Target width after expand
height	DimensionValue	source height	Target height after expand
borderRadius	number	source radius	Target corner radius. Set to 0 for no rounding.
collapseDuration	number	—	Duration of the collapse animation in ms. Falls back to the source's duration.
contentOffsetY	number	0	Vertical offset for content snapshot in wrapper mode
contentCentered	boolean	false	Center content snapshot horizontally in wrapper mode

useMorphTarget(options)

Hook that provides a dismiss function for collapsing back to the source card. The navigation object must support goBack() — works with React Navigation, expo-router, or any navigator that implements it.

const { dismiss } = useMorphTarget({
  sourceTag: route.params.sourceTag,
  navigation,
});

Note: The detail screen should be presented as a modal (e.g. transparentModal or fullScreenModal in React Navigation) so the source screen remains mounted underneath during the animation. Make sure to disable any built-in navigation transitions (e.g. animation: 'none' in React Navigation) — the morph animation replaces the screen transition entirely, and combining both will look broken.

Imperative API

For more control, use the imperative functions:

import {
  morphExpand,
  morphCollapse,
  getViewTag,
} from 'react-native-morph-card';

// Expand from source to target
await morphExpand(sourceRef, targetRef);

// Collapse back (pass the sourceTag)
await morphCollapse(sourceTag);

// Get the native view tag from a ref
const tag = getViewTag(viewRef);

## Running the example app

The example app lives in the `example/` directory and uses [`react-native-test-app`](https://github.com/nicklasmoeller/react-native-test-app) to manage the native projects.

### Prerequisites

| Tool | Version |
|------|---------|
| Node.js | >= 18 |
| Yarn | 1.x |
| Ruby | >= 2.7 (for CocoaPods) |
| CocoaPods | ~> 1.15 |
| Xcode | >= 15 (iOS) |
| Android Studio | latest (Android) |
| JDK | 17 |

Make sure you have an iOS Simulator or Android Emulator available.

### 1. Install dependencies

From the repository root:

```sh
# Install root (library) dependencies
yarn install

# Install example app dependencies
cd example
yarn install

2. Run on iOS

# Install CocoaPods (from example/ios)
cd ios
bundle install
bundle exec pod install
cd ..

# Start Metro and build
yarn ios

This opens the app on the iOS Simulator. Metro starts automatically.

If you prefer to build from Xcode, open example/ios/MorphCardExample.xcworkspace and press Run.

3. Run on Android

Make sure an Android emulator is running (or a device is connected), then from example/:

yarn android

Gradle will download dependencies on first run — this can take a few minutes.

4. Start Metro separately (optional)

If you want to start the Metro bundler on its own (e.g. to see logs in a dedicated terminal):

cd example
yarn start

Then run yarn ios or yarn android in another terminal.

Building JS bundles manually

Only needed if you want to test pre-built bundles (not required for normal development):

cd example
yarn build:ios
yarn build:android

Troubleshooting

Problem	Fix
pod install fails	Run bundle install first, then bundle exec pod install
Android build fails on first run	Make sure ANDROID_HOME is set and an emulator/device is available
Metro can't find react-native-morph-card	Run yarn install at the repo root first
Duplicate module errors	Delete node_modules in both root and example/, then reinstall

Contributing

Contributions are welcome! If you find a bug or have a feature request, please open an issue. Pull requests are appreciated — just make sure to open an issue first so we can discuss the approach.

Roadmap

• Support for more screen presentation styles (e.g. iOS modal sheet, page sheet)
• Shared element transitions between arbitrary views
• Gesture-driven collapse (drag to dismiss)
• Spring physics configuration props

License

MIT