Bottom Sheet Stepper

A lightweight and customizable step-based component for React Native, built on top of @gorhom/bottom-sheet. Perfect for building multi-step flows like wizards, onboarding screens, or custom forms — all in a sleek bottom sheet.

✨ Features

• 🎯 Multi-step navigation with onNextPress, onBackPress, and optional onEnd
• 📱 Smooth animations with react-native-reanimated
• 🧩 Fully customizable styles and layout
• 🧠 Built-in height animation & cleanup handling
• 🔁 Programmatic control with present() and dismiss()

🚀 Installation

1npm install bottom-sheet-stepper
2# or
3yarn add bottom-sheet-stepper

Peer Dependencies

Make sure you have the following installed in your project:

1npm install react-native-reanimated react-native-gesture-handler @gorhom/bottom-sheet

Then wrap your app with the necessary providers:

1import { GestureHandlerRootView } from "react-native-gesture-handler";
2import { BottomSheetModalProvider } from "@gorhom/bottom-sheet";
3
4<GestureHandlerRootView style={{ flex: 1 }}>
5  <BottomSheetModalProvider>
6    <App />
7  </BottomSheetModalProvider>
8</GestureHandlerRootView>;

🧱 Usage

1import React, { useRef } from "react";
2import BottomSheetStepper, {
3  BottomSheetStepperRef,
4  StepComponentProps,
5} from "bottom-sheet-stepper";
6
7const Step1 = ({ onNextPress }: StepComponentProps) => (
8  <View>
9    <Text>Step 1</Text>
10    <Button title="Next" onPress={onNextPress} />
11  </View>
12);
13
14const Step2 = ({ onBackPress, onEnd }: StepComponentProps) => (
15  <View>
16    <Text>Step 2</Text>
17    <Button title="Back" onPress={onBackPress} />
18    <Button title="Finish" onPress={onEnd} />
19  </View>
20);
21
22const App = () => {
23  const stepperRef = useRef<BottomSheetStepperRef>(null);
24
25  return (
26    <>
27      <Button
28        title="Open Stepper"
29        onPress={() => stepperRef.current?.present()}
30      />
31
32      <BottomSheetStepper ref={stepperRef} steps={[Step1, Step2]} />
33    </>
34  );
35};

📘 API Reference

Props

Name	Type	Description
steps	((props: StepComponentProps) => React.ReactNode)[]	Array of step render functions
style	StyleProp<ViewStyle>	Optional style applied to step container
bottomInset	number	Padding at bottom of the sheet (default: 20)
horizontalInset	number	Horizontal margin of the sheet (default: 24)
disablePanDownToClose	boolean	Disabling the pan to close gesture
disableBackDropPressToClose	boolean	Disabling the background press closing the modal

Step Props (StepComponentProps)

Passed to each step component:

1type StepComponentProps = {
2  onNextPress: () => void;
3  onBackPress: () => void;
4  onEnd?: () => void;
5};

🔧 Imperative API

You can control the sheet externally via ref:

1const ref = useRef<BottomSheetStepperRef>(null);
2
3ref.current?.present();
4ref.current?.dismiss();

🧪 Example Use Cases

• Onboarding flows
• Step-by-step data collection
• Multi-step modals
• Form wizards

🛠 Built With

• @gorhom/bottom-sheet
• react-native-reanimated
• react-native-gesture-handler

📄 License

Made with ❤️ by @mahdidavoodi7