BottomSheet

Import

import { BottomSheet } from 'heroui-native';

Anatomy

<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay>...</BottomSheet.Overlay>
    <BottomSheet.Content>
      <BottomSheet.Close />
      <BottomSheet.Title>...</BottomSheet.Title>
      <BottomSheet.Description>...</BottomSheet.Description>
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

• BottomSheet: Root component that manages open state and provides context to child components.
• BottomSheet.Trigger: Pressable element that opens the bottom sheet when pressed.
• BottomSheet.Portal: Renders bottom sheet content in a portal with full window overlay.
• BottomSheet.Overlay: Background overlay that covers the screen, typically closes bottom sheet when pressed.
• BottomSheet.Content: Main bottom sheet container using @gorhom/bottom-sheet for rendering with gesture support.
• BottomSheet.Close: Close button for the bottom sheet. Can accept custom children or uses default close icon.
• BottomSheet.Title: Bottom sheet title text with semantic heading role and accessibility linking.
• BottomSheet.Description: Bottom sheet description text that provides additional context with accessibility linking.

Usage

Basic Bottom Sheet

Simple bottom sheet with title, description, and close button.

<BottomSheet>
  <BottomSheet.Trigger asChild>
    <Button>Open Bottom Sheet</Button>
  </BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content>
      <BottomSheet.Close />
      <BottomSheet.Title>...</BottomSheet.Title>
      <BottomSheet.Description>...</BottomSheet.Description>
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

Detached Bottom Sheet

Bottom sheet that appears detached from the bottom edge with custom spacing.

<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content
      detached={true}
      bottomInset={insets.bottom + 12}
      className="mx-4"
      backgroundClassName="rounded-[32px]"
    >
      ...
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

Scrollable with Snap Points

Bottom sheet with multiple snap points and scrollable content.

To make scrollable content work correctly inside BottomSheet.Content, follow these base principles:

• Use a scrollable from @gorhom/bottom-sheet (e.g. BottomSheetScrollView, BottomSheetFlatList, BottomSheetSectionList, BottomSheetVirtualizedList). A plain ScrollView/FlatList from react-native will let the sheet intercept the scroll gesture.
• On BottomSheet.Content, disable over-drag and dynamic sizing so the sheet does not grow with its content or absorb the scroll: enableOverDrag={false} and enableDynamicSizing={false}.
• Give BottomSheet.Content a fixed height via contentContainerClassName="h-full" (or any other fixed height). The constraint must be on BottomSheet.Content, not on the scrollable child — the scrollable needs a bounded parent to scroll inside.

import { BottomSheetScrollView } from '@gorhom/bottom-sheet';

<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content
      snapPoints={['40%', '80%']}
      enableOverDrag={false}
      enableDynamicSizing={false}
      contentContainerClassName="h-full"
    >
      <BottomSheetScrollView>...</BottomSheetScrollView>
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>;

See the full example with a sticky footer (BottomSheetFooter) in the GitHub repository.

Custom Overlay

Replace the default overlay with custom content like blur effects.

import { useBottomSheet, useBottomSheetAnimation } from 'heroui-native';
import { StyleSheet, Pressable } from 'react-native';
import { interpolate, useDerivedValue } from 'react-native-reanimated';
import { AnimatedBlurView } from './animated-blur-view';
import { useUniwind } from 'uniwind';

export const BottomSheetBlurOverlay = () => {
  const { theme } = useUniwind();
  const { onOpenChange } = useBottomSheet();
  const { progress } = useBottomSheetAnimation();

  const blurIntensity = useDerivedValue(() => {
    return interpolate(progress.get(), [0, 1, 2], [0, 40, 0]);
  });

  return (
    <Pressable
      style={StyleSheet.absoluteFill}
      onPress={() => onOpenChange(false)}
    >
      <AnimatedBlurView
        blurIntensity={blurIntensity}
        tint={theme === 'dark' ? 'dark' : 'systemUltraThinMaterialDark'}
        style={StyleSheet.absoluteFill}
      />
    </Pressable>
  );
};

<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheetBlurOverlay />
    <BottomSheet.Content>...</BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

With Keyboard-Aware Input

When rendering an Input or InputOTP inside BottomSheet.Content, use the useBottomSheetAwareHandlers hook to wire keyboard avoidance handlers. Pass the returned onFocus / onBlur to your input.

Note: useBottomSheetAwareHandlers must be used inside a BottomSheet. Call it from a child component rendered inside BottomSheet.Content — outside of a BottomSheet context the returned handlers are no-ops.

For scrollable content, also configure BottomSheet.Content with keyboardBehavior="extend" (or "interactive") and keyboardShouldPersistTaps="handled" on the scrollable so taps don't dismiss the keyboard before reaching their target.

import { BottomSheet, Input, useBottomSheetAwareHandlers } from 'heroui-native';

const BottomSheetTextInput = () => {
  const { onFocus, onBlur } = useBottomSheetAwareHandlers();

  return <Input placeholder="Type here..." onFocus={onFocus} onBlur={onBlur} />;
};

<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content keyboardBehavior="extend">
      <BottomSheetTextInput />
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>;

See full examples for Input and InputOTP inside a bottom sheet.

Example

import { BottomSheet, Button } from 'heroui-native';
import { useState } from 'react';
import { View } from 'react-native';
import { withUniwind } from 'uniwind';
import Ionicons from '@expo/vector-icons/Ionicons';

const StyledIonicons = withUniwind(Ionicons);

export default function BottomSheetExample() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <BottomSheet isOpen={isOpen} onOpenChange={setIsOpen}>
      <BottomSheet.Trigger asChild>
        <Button variant="secondary">Open Bottom Sheet</Button>
      </BottomSheet.Trigger>
      <BottomSheet.Portal>
        <BottomSheet.Overlay />
        <BottomSheet.Content>
          <View className="items-center mb-5">
            <View className="size-20 items-center justify-center rounded-full bg-green-500/10">
              <StyledIonicons
                name="shield-checkmark"
                size={40}
                className="text-green-500"
              />
            </View>
          </View>
          <View className="mb-8 gap-2 items-center">
            <BottomSheet.Title className="text-center">
              Keep yourself safe
            </BottomSheet.Title>
            <BottomSheet.Description className="text-center">
              Update your software to the latest version for better security and
              performance.
            </BottomSheet.Description>
          </View>
          <View className="gap-3">
            <Button onPress={() => setIsOpen(false)}>Update Now</Button>
            <Button variant="tertiary" onPress={() => setIsOpen(false)}>
              Later
            </Button>
          </View>
        </BottomSheet.Content>
      </BottomSheet.Portal>
    </BottomSheet>
  );
}

You can find more examples in the GitHub repository.

API Reference

BottomSheet

Animation Configuration

Animation configuration for bottom sheet root component. Can be:

• "disable-all": Disable all animations including children
• undefined: Use default animations

BottomSheet.Trigger

BottomSheet.Portal

BottomSheet.Overlay

Animation Configuration

Animation configuration for bottom sheet overlay component. Can be:

• false or "disabled": Disable all animations
• true or undefined: Use default animations
• object: Custom animation configuration (excluding entering and exiting properties)

BottomSheet.Content

Note: You can use all components from @gorhom/bottom-sheet inside the content, such as BottomSheetView, BottomSheetScrollView, BottomSheetFlatList, etc.

BottomSheet.Close

BottomSheet.Close extends CloseButton and automatically handles bottom sheet dismissal when pressed.

BottomSheet.Title

BottomSheet.Description

Hooks

useBottomSheet

Hook to access bottom sheet primitive context.

const { isOpen, onOpenChange } = useBottomSheet();

useBottomSheetAnimation

Hook to access bottom sheet animation context for advanced customization.

const { progress } = useBottomSheetAnimation();

useBottomSheetAwareHandlers

Hook that returns onFocus and onBlur handlers for keyboard avoidance when an Input or InputOTP is rendered inside BottomSheet.Content. Must be used inside a BottomSheet — outside of a BottomSheet context, the returned handlers are no-ops.

const { onFocus, onBlur } = useBottomSheetAwareHandlers();

Special Notes

Element Inspector (iOS)

BottomSheet uses FullWindowOverlay on iOS, which renders in a separate native window. This breaks the React Native element inspector. To enable the inspector during development, set disableFullWindowOverlay={true} on BottomSheet.Portal. Tradeoff: the bottom sheet will not appear above native modals when disabled.

Handling Close Callbacks

It's recommended to use BottomSheet's onOpenChange prop for handling close callbacks, as it reliably fires for all close scenarios (swiping down, pressing overlay, pressing close button, programmatic close, etc.).

<BottomSheet
  isOpen={isOpen}
  onOpenChange={(value) => {
    setIsOpen(value);
    if (!value) {
      // This callback runs whenever the bottom sheet closes
      // regardless of how it was closed
      yourCallbackOnClose();
    }
  }}
>
  ...
</BottomSheet>

Note: BottomSheet.Content's onClose prop (from @gorhom/bottom-sheet) has limitations and will only fire when the bottom sheet is closed by swiping down. It won't fire when closing via overlay press, close button, or programmatic close. For reliable close callbacks, always use BottomSheet's onOpenChange prop instead.