Bottom Sheet Stepper

You can pass a shared object to BottomSheetStepper. This object is automatically injected into every step function via StepComponentProps. The type of shared is inferred from the object you provide, ensuring type safety within your step components without manual casting.

// `user` is your own data — its type flows into every step, no annotation needed
<BottomSheetStepper
  ref={stepperRef}
  shared={{ user }}
  initialStep={0}
  steps={[
    ({ shared, onNextPress }) => (
      <AccountStep user={shared.user} onNext={onNextPress} />
    ),
    ({ shared, onEnd }) => (
      <ConfirmStep user={shared.user} onDone={onEnd} />
    ),
  ]}
/>;

Before using the stepper, ensure your application is wrapped in GestureHandlerRootView and BottomSheetModalProvider so the sheet and gestures function correctly.

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

<GestureHandlerRootView style={{ flex: 1 }}>
  <BottomSheetModalProvider>
    <App />
  </BottomSheetModalProvider>
</GestureHandlerRootView>;

If you want to clear the existing starter code and begin with a blank project, run the reset-project script. This moves the current starter code into an app-example directory and creates a fresh, empty app directory for your development.

npm run reset-project

To use bottom-sheet-stepper, you can either copy BottomSheetStepper.tsx directly from the source or install it via npm. You must also install the required peer dependencies: react-native-reanimated, react-native-gesture-handler, and @gorhom/bottom-sheet.

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

To run the provided example project, install the necessary dependencies using npm and then start the Expo development server. Once started, you can open the app in a development build, an Android emulator, an iOS simulator, or Expo Go.

npm install
npx expo start

The BottomSheetStepper is controlled via its ref. Use the following methods to manage the visibility of the stepper:

• present(): Opens the bottom sheet at the initialStep.
• dismiss(): Closes the bottom sheet.

The BottomSheetStepperProps<TShared> object defines how the stepper behaves and what data it carries:

• steps: An array of functions that return a React.ReactNode. Each function receives StepComponentProps<TShared>.
• shared: Data passed to every step. The type of this prop is used to infer the type of shared inside each step's props.
• initialStep: The zero-based index where the flow starts and returns to upon closing. Defaults to 0.
• style: Custom style for the content container.
• bottomInset: Padding at the bottom of the sheet. Defaults to 20.
• horizontalInset: Horizontal margin for the bottom sheet. Defaults to 24.
• disablePanDownToClose: If true, prevents the user from swiping the sheet down to close it.
• disableBackDropPressToClose: If true, prevents tapping the backdrop from dismissing the sheet.

The BottomSheetStepper component accepts the following props to customize the stepper behavior and appearance:

Each function in the steps array receives a StepComponentProps<TShared> object. Use these props to navigate the flow and access shared state:

• onNextPress: Call this to move to the next step. If it is the last step, the sheet will close.
• onBackPress: Call this to move to the previous step. If it is the first step, the sheet will close.
• onEnd: Call this to manually close the sheet (useful for completion actions).
• shared: The data provided via the shared prop on the main BottomSheetStepper component. It is automatically typed based on the shared prop.

type MyData = { name: string };

const steps = [
  ({ onNextPress, shared }: StepComponentProps<MyData>) => (
    <View>
      <Text>{shared.name}</Text>
      <Button title="Next" onPress={onNextPress} />
    </View>
  )
];

Each function in the steps array receives a StepComponentProps<TShared> object. This object provides the necessary tools to navigate the stepper and access data shared across the entire flow.

Properties

• onNextPress: Function to trigger the transition to the next step.
• onBackPress: Function to trigger the transition to the previous step.
• onEnd: Optional callback triggered when the stepper reaches the end of the flow.
• shared: The data passed from the shared prop of the BottomSheetStepper. It is typed via the TShared generic, allowing for type-safe access to shared state without manual casting.

type MySharedData = { name: string };

const steps = [
  ({ shared, onNextPress }: StepComponentProps<MySharedData>) => (
    <View>
      <Text>{shared.name}</Text>
      <Button title="Next" onPress={onNextPress} />
    </View>
  ),
];