React Native Step Bottom Sheet

A customizable step-by-step bottom sheet component for React Native with smooth animations, perfect for onboarding flows, wizards, and multi-step forms.

Features

• 🎯 Step-by-step navigation with smooth animations
• 🎨 Fully customizable styling and behavior
• 📱 Built on @gorhom/bottom-sheet for reliable performance
• ⚡ Dynamic height adjustment based on content
• 🎭 Animated transitions between steps
• 🎮 Gesture support with pan-to-close functionality
• 🔧 TypeScript support with full type definitions
• 🎪 Flexible step components - use any React component as a step

Installation

npm install react-native-step-bottom-sheet
# or
yarn add react-native-step-bottom-sheet

Peer Dependencies

Make sure you have these peer dependencies installed:

npm install @gorhom/bottom-sheet react-native-gesture-handler react-native-reanimated react-native-safe-area-context
# or
yarn add @gorhom/bottom-sheet react-native-gesture-handler react-native-reanimated react-native-safe-area-context

Quick Start

App Setup

Important: Before using the component, you need to set up the required providers in your app's root layout.

For Expo Router Apps

Add the providers to your app/_layout.tsx:

import { Slot } from "expo-router";
import { GestureHandlerRootView } from "react-native-gesture-handler";
import { BottomSheetModalProvider } from "@gorhom/bottom-sheet";

export default function Layout() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <BottomSheetModalProvider>
        <Slot />
      </BottomSheetModalProvider>
    </GestureHandlerRootView>
  );
}

For React Navigation Apps

Add the providers to your App.tsx or root component:

import React from 'react';
import { NavigationContainer } from '@react-navigation/native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { BottomSheetModalProvider } from '@gorhom/bottom-sheet';
import YourNavigator from './YourNavigator';

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>
      <NavigationContainer>
        <BottomSheetModalProvider>
          <YourNavigator />
        </BottomSheetModalProvider>
      </NavigationContainer>
    </GestureHandlerRootView>
  );
}

Basic Usage

import React, { useRef, useCallback } from 'react';
import { View, Text, TouchableOpacity } from 'react-native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import BottomSheet from '@gorhom/bottom-sheet';
import { StepBottomSheet } from 'react-native-step-bottom-sheet';

// Define your step components
const WelcomeStep = () => (
  <View style={{ padding: 20 }}>
    <Text style={{ fontSize: 24, fontWeight: 'bold' }}>Welcome! 🎉</Text>
    <Text>Get started with our amazing app</Text>
  </View>
);

const SetupStep = () => (
  <View style={{ padding: 20 }}>
    <Text style={{ fontSize: 24, fontWeight: 'bold' }}>Setup 🔧</Text>
    <Text>Let's configure your preferences</Text>
  </View>
);

const ReadyStep = () => (
  <View style={{ padding: 20 }}>
    <Text style={{ fontSize: 24, fontWeight: 'bold' }}>Ready! 🚀</Text>
    <Text>You're all set to begin</Text>
  </View>
);

const App = () => {
  const bottomSheetRef = useRef<BottomSheet>(null);
  const steps = [WelcomeStep, SetupStep, ReadyStep];

  const handleOpenPress = useCallback(() => {
    bottomSheetRef.current?.snapToIndex(0);
  }, []);

  const handleClosePress = useCallback(() => {
    bottomSheetRef.current?.close();
  }, []);

  return (
    <GestureHandlerRootView style={{ flex: 1, backgroundColor: "gray" }}>
      <View style={{ flex: 1, justifyContent: 'center', alignItems: 'center' }}>
        <TouchableOpacity onPress={handleOpenPress}>
          <Text>Open</Text>
        </TouchableOpacity>
      </View>
      <StepBottomSheet
        ref={bottomSheetRef}
        steps={steps}
        onClose={handleClosePress}
      />
    </GestureHandlerRootView>
  );
};

Advanced Usage with Custom Styling

import React from 'react';
import { View, Button } from 'react-native';
import { StepBottomSheet, useStepBottomSheet } from 'react-native-step-bottom-sheet';

const App = () => {
  const { ref, open, close, currentStep } = useStepBottomSheet();
  
  const handleStepChange = (stepIndex: number) => {
    console.log('Current step:', stepIndex);
  };

  return (
    <View style={{ flex: 1 }}>
      <Button title="Open Custom Steps" onPress={open} />
      
      <StepBottomSheet
        ref={ref}
        steps={[WelcomeStep, SetupStep, ReadyStep]}
        onClose={close}
        onStepChange={handleStepChange}
        stepContentProps={{
          initialStep: 0,
          showNavigation: true,
          showIndicators: true,
          navigationLabels: {
            previous: 'Back',
            next: 'Continue'
          },
          styles: {
            container: {
              backgroundColor: '#f8f9fa',
              borderTopLeftRadius: 20,
              borderTopRightRadius: 20,
            },
            navigationButton: {
              backgroundColor: '#007AFF',
              borderRadius: 12,
            },
            stepIndicatorActive: {
              backgroundColor: '#007AFF',
            }
          }
        }}
        snapPoints={['90%']}
        enablePanDownToClose={true}
        backdropProps={{
          opacity: 0.5,
        }}
      />
    </View>
  );
};

API Reference

StepBottomSheet Props

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | React.ComponentType[] | Required | Array of React components to render as steps | | onClose | () => void | undefined | Callback when bottom sheet is closed | | onStepChange | (stepIndex: number) => void | undefined | Callback when step changes | | stepContentProps | Partial<StepContentProps> | {} | Props to pass to the StepContent component | | snapPoints | string[] | ["100%"] | Bottom sheet snap points | | enablePanDownToClose | boolean | true | Enable pan down to close gesture | | enableDynamicSizing | boolean | true | Enable dynamic sizing based on content | | backdropProps | object | {} | Props for the backdrop component |

StepContentProps

| Prop | Type | Default | Description | |------|------|---------|-------------| | steps | React.ComponentType[] | Required | Array of step components | | onClose | () => void | undefined | Close callback | | onStepChange | (stepIndex: number) => void | undefined | Step change callback | | initialStep | number | 0 | Initial step index | | showNavigation | boolean | true | Show navigation buttons | | showIndicators | boolean | true | Show step indicators | | navigationLabels | {previous: string, next: string} | {previous: 'Previous', next: 'Next'} | Navigation button labels | | styles | object | {} | Custom styles object |

useStepBottomSheet Hook

Returns an object with:

| Property | Type | Description | |----------|------|-------------| | ref | RefObject | Ref to pass to StepBottomSheet | | open | () => void | Function to open the bottom sheet | | close | () => void | Function to close the bottom sheet | | goToStep | (stepIndex: number) => void | Function to navigate to specific step | | currentStep | number | Current step index | | isOpen | boolean | Whether the bottom sheet is open |

Styling

The component supports extensive styling customization through the styles prop in stepContentProps:

const customStyles = {
  container: {
    backgroundColor: '#ffffff',
    borderTopLeftRadius: 30,
    borderTopRightRadius: 30,
  },
  navigationButton: {
    backgroundColor: '#007AFF',
    paddingHorizontal: 24,
    paddingVertical: 12,
    borderRadius: 8,
  },
  navigationButtonDisabled: {
    backgroundColor: '#E5E5E5',
  },
  navigationButtonText: {
    color: 'white',
    fontSize: 16,
    fontWeight: '600',
  },
  navigationButtonTextDisabled: {
    color: '#999',
  },
  stepIndicator: {
    width: 10,
    height: 10,
    borderRadius: 5,
    backgroundColor: '#E5E5E5',
  },
  stepIndicatorActive: {
    backgroundColor: '#007AFF',
  },
};

Examples

Check out the /example folder for complete working examples including:

• Basic step navigation
• Custom styling
• Dynamic content
• Integration with forms
• Onboarding flows

Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

License

MIT License - see LICENSE file for details.

Credits

Built on top of the excellent @gorhom/bottom-sheet library.