React Native Sheet Transitions 🎭

Beautiful iOS-like sheet transitions for React Native, Expo Go, and Web. Provides smooth, native-feeling custom modal transitions with gesture-based interactions.

Features ✨

• 🔄 Smooth scale transitions
• 👆 Gesture-based dismissal with haptic feedback
• 📱 iOS-like modal animations
• 🎨 Customizable animations
• 🌗 Two animation modes: incremental & decremental
• 🎯 Border radius sync with gestures
• 🔍 Opacity animations
• 📐 Multi-directional dragging support

⚠️ Work in Progress: This package is under active development and not yet recommended for production use. Breaking changes may occur frequently. Feel free to contribute by submitting PRs or reporting issues!

Installation 📦

npm install react-native-sheet-transitions
# or
yarn add react-native-sheet-transitions
# or
bun add react-native-sheet-transitions

Peer Dependencies

npm install react-native-reanimated react-native-gesture-handler

Basic Usage 🚀

1. Wrap your app with SheetProvider:

import { SheetProvider } from 'react-native-sheet-transitions'

export default function App() {
  return (
    <SheetProvider>
      <Navigation />
    </SheetProvider>
  )
}

2. Use SheetScreen in your modal:

import { SheetScreen } from 'react-native-sheet-transitions'

export default function ModalScreen() {
  const router = useRouter()
  
  return (
    <SheetScreen 
      onClose={() => router.back()}
      dragDirections={{ toBottom: true }}
      opacityOnGestureMove={true}
      containerRadiusSync={true}
    >
      <YourContent />
    </SheetScreen>
  )
}

API Reference 📚

SheetProvider Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | springConfig | SpringConfig | { damping: 15, stiffness: 150, mass: 0.5 } | Spring animation configuration | | resizeType | 'incremental' \| 'decremental' | 'decremental' | Scale animation mode | | enableForWeb | boolean | false | Enable animations on web platform (not recommended) |

SheetScreen Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | onClose | () => void | required | Callback when sheet is dismissed | | scaleFactor | number | 0.83 | Scale factor for background content | | dragThreshold | number | 150 | Distance required to trigger dismiss | | springConfig | SpringConfig | { damping: 15, stiffness: 60, mass: 0.6, restDisplacementThreshold: 0.01, restSpeedThreshold: 0.01 } | Spring animation config | | dragDirections | DragDirections | { toBottom: true } | Enabled drag directions | | isScrollable | boolean | false | Enable scroll handling for content | | opacityOnGestureMove | boolean | false | Enable opacity animation during drag | | containerRadiusSync | boolean | true | Sync border radius with drag | | initialBorderRadius | number | 50 | Initial border radius value | | style | ViewStyle | undefined | Additional container styles | | disableSyncScaleOnDragDown | boolean | false | Disable scale sync during drag | | customBackground | ReactNode | undefined | Custom background component with fade animation | | onOpenStart | () => void | undefined | Called when sheet starts opening animation | | onOpenEnd | () => void | undefined | Called when sheet opening animation completes | | onCloseStart | () => void | undefined | Called when user gesture triggers close | | onCloseEnd | () => void | undefined | Called when close animation completes (replaces onClose if provided) | | onBelowThreshold | () => void | undefined | Called when drag goes below threshold after exceeding it | | disableRootScale | boolean | false | Disable background scaling effect | | disableSheetContentResizeOnDragDown | boolean | false | Disable sheet content scaling during drag down |

Types

interface SpringConfig {
  damping?: number
  stiffness?: number
  mass?: number
  velocity?: number
}

interface DragDirections {
  toTop?: boolean
  toBottom?: boolean
  toLeft?: boolean
  toRight?: boolean
}

Advanced Usage 🔧

Incremental Scale Mode

Background scales up instead of down:

<SheetProvider resizeType="incremental">
  <App />
</SheetProvider>

Custom Animation Config

<SheetScreen 
  springConfig={{
    damping: 15,
    stiffness: 120,
    mass: 0.8
  }}
  scaleFactor={0.85}
  dragThreshold={100}
  opacityOnGestureMove={true}
  containerRadiusSync={true}
  initialBorderRadius={40}
>
  <Content />
</SheetScreen>

Multi-directional Dragging

<SheetScreen 
  dragDirections={{
    toBottom: true,
    toLeft: true,
    toRight: true
  }}
  onClose={handleClose}
>
  <Content />
</SheetScreen>

Custom Background

You can add a custom background component that fades in/out with the modal:

import { BlurView } from 'expo-blur'

<SheetScreen 
  customBackground={
    <BlurView 
      intensity={20} 
      style={StyleSheet.absoluteFill}
    />
  }
  onClose={handleClose}
>
  <Content />
</SheetScreen>

The background component will:

• Fade in when modal opens
• Fade out when modal closes
• Be positioned absolutely behind the modal content
• Not sync opacity with drag gestures

Expo Router Integration 🔗

Configure your modal screen:

// app/_layout.tsx
import { Stack } from 'expo-router'
import { SheetProvider } from 'react-native-sheet-transitions'

export default function Layout() {
  return (
    <SheetProvider>
      <Stack>
        <Stack.Screen name="index" />
        <Stack.Screen 
          name="modal" 
          options={{
            presentation: 'transparentModal',
            contentStyle: { backgroundColor: 'transparent' }
          }}
        />
      </Stack>
    </SheetProvider>
  )
}

Contributing 🤝

Pull requests are welcome! For major changes:

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a pull request

Lifecycle Callbacks

The SheetScreen component provides several callbacks for precise control:

interface SheetScreenProps {
  // Called when sheet starts opening animation
  onOpenStart?: () => void
  
  // Called when sheet opening animation completes
  onOpenEnd?: () => void
  
  // Called when user drags above threshold
  onCloseStart?: () => void
  
  // Called when user drags below threshold
  onBelowThreshold?: () => void
  
  // Called when close animation completes
  onCloseEnd?: () => void
}

Example with Haptic Feedback

<SheetScreen
  onCloseStart={() => {
    // Warn user they can release to close
    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Warning)
  }}
  onBelowThreshold={() => {
    // Reset state when going below threshold
  }}
  onCloseEnd={() => {
    // Success haptic when sheet closes
    Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success)
    router.back()
  }}
>
  {/* content */}
</SheetScreen>

Platform Specific Behavior 📱

Background Scaling

The background scaling effect (where the previous screen scales down when the sheet opens) is:

• ✅ Enabled by default on iOS
• ❌ Disabled by default on Android and Web
• Can be disabled on iOS using disableRootScale={true}

<SheetScreen 
  disableRootScale={true}  // Disable background scaling even on iOS
  onClose={handleClose}
>
  <Content />
</SheetScreen>

Web Platform Support ⚠️

By default, sheet transitions are disabled on web platforms for better UX and accessibility. Web modals should follow web platform conventions.

If you need to enable animations on web:

<SheetProvider enableForWeb={true}>
  <App />
</SheetProvider>

Note: Enabling sheet transitions on web is not recommended as it can:

• Interfere with native web accessibility features
• Create inconsistent UX across different browsers
• Impact performance on lower-end devices
• Break expected web modal behaviors

Consider using native web modals or dialogs for better user experience on web platforms.

Roadmap 🗺️

High Priority

• [ ] Fix Scrolling gesture handling and momentum issues
• [ ] Multiple Portal support for nested sheets
• [ ] iOS-like sheet detents (snap points)
  • Configurable small, medium, large positions
  • Custom snap point values
  • Default snap point configuration
  • Smooth animations between detents
  • Gesture-based snapping behavior

Plans

• [ ] Enhanced gesture controls
  • Velocity-based dismissal
  • Directional lock
• [ ] Accessibility improvements
  • Screen reader support
  • Reduced motion preferences
  • Focus support
• [ ] More animations
  • Shared element transitions
• [ ] Better web support
  • Keyboard navigation
  • Focus trapping

License 📄

MIT © saulamsal