Bottom SheetUpdated

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.

<BottomSheet>
  <BottomSheet.Trigger>...</BottomSheet.Trigger>
  <BottomSheet.Portal>
    <BottomSheet.Overlay />
    <BottomSheet.Content snapPoints={['25%', '50%', '90%']}>
      <ScrollView>...</ScrollView>
    </BottomSheet.Content>
  </BottomSheet.Portal>
</BottomSheet>

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>

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();

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.