BottomSheet

A bottom sheet component for React Native built on top of

with gluestack-ui styling and NativeWind className support.

Important Note

Note: BottomSheet is not supported in Next.js. It is intended for React Native and Expo (mobile/web via React Native) environments only.

@gorhom/bottom-sheet

relies on React Native Reanimated and Gesture Handler which are not compatible with Next.js.

This is an illustration of the BottomSheet component.

React Native / Expo onlyThis component is not supported in Next.js. Preview it in a React Native or Expo environment.

With Search Input

A bottom sheet with a keyboard-aware search input using BottomSheetTextInput. Typing filters the list in real time without dismissing the keyboard.

React Native / Expo onlyThis component is not supported in Next.js. Preview it in a React Native or Expo environment.

With Footer

A bottom sheet with a sticky BottomSheetFooter containing action buttons. Items can be multi-selected without closing the sheet, and the Confirm button shows the selected count.

React Native / Expo onlyThis component is not supported in Next.js. Preview it in a React Native or Expo environment.

With Snap Points

A bottom sheet with multiple snap points controlled programmatically via a ref. Demonstrates open, close, expand, collapse, and snapToIndex using the imperative BottomSheetRef handle.

React Native / Expo onlyThis component is not supported in Next.js. Preview it in a React Native or Expo environment.

Installation

Run the following command:

npx gluestack-ui@alpha add bottomsheet

This command will copies all the code from git repo — excluding the docs and examples folders — into your project's

components/ui

directory.

API Reference

To use this component in your project, include the following import statement in your file.

import {
  BottomSheet,
  BottomSheetBackdrop,
  BottomSheetContent,
  BottomSheetDragIndicator,
  BottomSheetFlatList,
  BottomSheetFooter,
  BottomSheetItem,
  BottomSheetItemText,
  BottomSheetPortal,
  BottomSheetScrollView,
  BottomSheetSectionList,
  BottomSheetTextInput,
  BottomSheetTrigger,
} from '@/components/ui/bottomsheet';

export default () => (
  <BottomSheet>
    <BottomSheetTrigger>
      <Text>Open BottomSheet</Text>
    </BottomSheetTrigger>
    <BottomSheetPortal
      snapPoints={['25%', '50%']}
      backdropComponent={BottomSheetBackdrop}
      handleComponent={BottomSheetDragIndicator}
    >
      <BottomSheetContent>
        <BottomSheetItem>
          <BottomSheetItemText>Item 1</BottomSheetItemText>
        </BottomSheetItem>
        <BottomSheetItem>
          <BottomSheetItemText>Item 2</BottomSheetItemText>
        </BottomSheetItem>
        <BottomSheetItem>
          <BottomSheetItemText>Item 3</BottomSheetItemText>
        </BottomSheetItem>
      </BottomSheetContent>
    </BottomSheetPortal>
  </BottomSheet>
);

Component Props

This section provides a comprehensive reference list for the component props, detailing descriptions, properties, types, and default behavior for easy project integration.

BottomSheet

The root context provider for the entire BottomSheet. Accepts a

ref

to control the sheet imperatively.

Props

Prop	Type	Default	Description
defaultSnapIndex	number	0	The index of snapPoints at which the bottom sheet initially opens when triggered.
onOpen	() => void	-	Callback fired when the bottom sheet opens.
onClose	() => void	-	Callback fired when the bottom sheet closes.
onChange	(index: number) => void	-	Callback fired whenever the sheet snaps to a new index. Receives the current snap index (-1 when closed).

Ref Methods

BottomSheet

forwards a ref exposing the following imperative methods:

Method	Signature	Description
open	(index?: number) => void	Opens the bottom sheet. Optionally pass a snap index; defaults to defaultSnapIndex.
close	() => void	Closes the bottom sheet.
snapToIndex	(index: number) => void	Snaps the sheet to the given snap point index.
expand	() => void	Expands the sheet to the highest snap point.
collapse	() => void	Collapses the sheet to the lowest snap point.

BottomSheetTrigger

Wraps React Native's

Pressable

. Pressing it opens the bottom sheet.

Prop	Type	Default	Description
index	number	-	Snap index to open the sheet at. Overrides defaultSnapIndex when provided.

Also inherits all props of React Native's

Pressable

BottomSheetPortal

The actual gorhom BottomSheet container. Inherits all props from

gorhom BottomSheet

Prop	Type	Default	Description
snapPoints	Array<string \| number>	-	Required. Points for the bottom sheet to snap to. Accepts numbers or percentage strings (e.g. '50%').
enablePanDownToClose	boolean	true	Enables closing the sheet by panning downward.
enableDynamicSizing	boolean	false	Enables the sheet height to be determined dynamically by its content.
closeOnBackdropPress	boolean	true	Closes the sheet when the backdrop is pressed.
backgroundClassName	string	-	NativeWind className applied to the sheet background surface.
handleIndicatorClassName	string	-	NativeWind className applied to the drag handle indicator.

BottomSheetBackdrop

Renders a semi-transparent backdrop behind the sheet. Inherits all props from

gorhom BottomSheetBackdrop

Prop	Type	Default	Description
disappearsOnIndex	number	-1	Snap index at which the backdrop disappears.
appearsOnIndex	number	0	Snap index at which the backdrop appears.
opacity	number	0.5	Opacity of the backdrop overlay.
pressBehavior	'close' \| 'collapse' \| 'none'	'close'	Defines what happens when the backdrop is pressed.