@react-buoy/bottom-sheet

A high-performance, fully customizable bottom sheet / modal component for React Native. Features both bottom sheet and floating window modes with smooth 60 FPS animations powered by the native driver.

Features

• 🚀 60 FPS Performance - Uses native driver for all animations
• 📱 Dual Modes - Bottom sheet and floating window modes
• 🎨 Fully Customizable - Custom headers, themes, and styles
• ✋ Touch Gestures - Drag to resize, double-tap to toggle mode, triple-tap to close
• 🔄 Smooth Transitions - Spring-based animations for natural feel
• 📐 Smart Boundaries - Respects safe areas and screen boundaries
• 💾 Zero Dependencies - Self-contained with built-in safe area detection
• 🎯 TypeScript - Full type safety and IntelliSense support

Installation

npm install @react-buoy/bottom-sheet
# or
yarn add @react-buoy/bottom-sheet
# or
pnpm add @react-buoy/bottom-sheet

Basic Usage

import React, { useState } from 'react';
import { View, Text, Button } from 'react-native';
import { BottomSheet } from '@react-buoy/bottom-sheet';

function MyComponent() {
  const [visible, setVisible] = useState(false);

  return (
    <View>
      <Button title="Open Bottom Sheet" onPress={() => setVisible(true)} />

      <BottomSheet
        visible={visible}
        onClose={() => setVisible(false)}
        header={{
          title: "My Bottom Sheet",
          subtitle: "Drag to resize"
        }}
      >
        <View style={{ padding: 20 }}>
          <Text>Your content here!</Text>
        </View>
      </BottomSheet>
    </View>
  );
}

Advanced Usage

Custom Theme

<BottomSheet
  visible={visible}
  onClose={() => setVisible(false)}
  theme={{
    primary: '#FF6B6B',
    secondary: '#4ECDC4',
    background: '#1A1A2E',
    panel: '#16213E',
    success: '#06FFA5',
  }}
>
  <YourContent />
</BottomSheet>

With Footer

<BottomSheet
  visible={visible}
  onClose={() => setVisible(false)}
  footer={
    <View style={{ padding: 16, borderTopWidth: 1, borderTopColor: '#ccc' }}>
      <Button title="Save" onPress={handleSave} />
    </View>
  }
  footerHeight={60}
>
  <YourContent />
</BottomSheet>

Custom Header

<BottomSheet
  visible={visible}
  onClose={() => setVisible(false)}
  header={{
    customContent: (
      <View style={{ padding: 16 }}>
        <Text style={{ fontSize: 18, fontWeight: 'bold' }}>
          Custom Header
        </Text>
      </View>
    )
  }}
>
  <YourContent />
</BottomSheet>

Floating Window Mode

<BottomSheet
  visible={visible}
  onClose={() => setVisible(false)}
  initialMode="floating"
  onModeChange={(mode) => console.log('Mode changed to:', mode)}
>
  <YourContent />
</BottomSheet>

Height Control

<BottomSheet
  visible={visible}
  onClose={() => setVisible(false)}
  initialHeight={500}
  minHeight={200}
  maxHeight={800}
>
  <YourContent />
</BottomSheet>

Props

BottomSheetProps

| Prop | Type | Default | Description | |------|------|---------|-------------| | visible | boolean | required | Controls visibility of the bottom sheet | | onClose | () => void | required | Callback when sheet should close | | children | ReactNode | required | Content to display in the sheet | | header | BottomSheetHeaderConfig | undefined | Header configuration | | styles | CustomStyles | {} | Custom styles for container and content | | minHeight | number | 100 | Minimum height in bottom sheet mode | | maxHeight | number | screen height - safe area | Maximum height in bottom sheet mode | | initialHeight | number | 400 | Initial height in bottom sheet mode | | initialMode | 'bottomSheet' \| 'floating' | 'bottomSheet' | Initial display mode | | onModeChange | (mode) => void | undefined | Callback when mode changes | | footer | ReactNode | undefined | Footer content (sticky at bottom) | | footerHeight | number | 0 | Height of footer for content padding | | onBack | () => void | undefined | Callback for back action (enables top-left corner tap) | | theme | Partial<Theme> | defaultTheme | Custom color theme |

BottomSheetHeaderConfig

| Prop | Type | Description | |------|------|-------------| | title | string | Header title text | | subtitle | string | Header subtitle text | | customContent | ReactNode | Custom header content (replaces title/subtitle) | | hideCloseButton | boolean | Hide the close button |

Gestures

• Drag Header - Resize bottom sheet or move floating window
• Double Tap Header - Toggle between bottom sheet and floating modes
• Triple Tap Header - Close the sheet
• Drag Corner (Floating) - Resize floating window
• Tap Top-Right Corner (Floating) - Close the sheet
• Tap Top-Left Corner (Floating) - Trigger back action (if onBack is provided)
• Fast Swipe Down - Close bottom sheet

Performance

This component is optimized for 60 FPS performance:

• All animations use useNativeDriver: true
• Transform-based positioning instead of layout changes
• Interpolation for calculations on the native thread
• Minimal JavaScript thread work during gestures
• No state updates during drag operations

TypeScript

Full TypeScript support with exported types:

import {
  BottomSheet,
  BottomSheetProps,
  BottomSheetMode,
  BottomSheetHeaderConfig
} from '@react-buoy/bottom-sheet';

License

MIT

Credits

Based on the proven JsModal component from the React Native Buoy toolkit.