CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-gorhom--bottom-sheet

A performant interactive bottom sheet with fully configurable options for React Native applications.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

Bottom Sheet

A performant interactive bottom sheet library for React Native that provides smooth gesture-driven interactions with fully configurable options. Built with TypeScript and React Native Reanimated v3, it supports various scrollable content types, keyboard handling, modal presentation, and accessibility features.

Package Information

  • Package Name: @gorhom/bottom-sheet
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install @gorhom/bottom-sheet
  • Peer Dependencies:
    • react-native-reanimated@>=3.16.0
    • react-native-gesture-handler@>=2.16.1

Core Imports

import BottomSheet, {
  BottomSheetModal,
  BottomSheetModalProvider,
  useBottomSheet,
  useBottomSheetModal
} from "@gorhom/bottom-sheet";

For specific components:

import {
  BottomSheetScrollView,
  BottomSheetFlatList,
  BottomSheetSectionList,
  BottomSheetHandle,
  BottomSheetBackdrop,
  BottomSheetTextInput
} from "@gorhom/bottom-sheet";

Basic Usage

import React, { useRef, useMemo } from 'react';
import { View, Text } from 'react-native';
import BottomSheet from '@gorhom/bottom-sheet';

const MyComponent = () => {
  const bottomSheetRef = useRef<BottomSheet>(null);
  const snapPoints = useMemo(() => ['25%', '50%', '90%'], []);

  return (
    <View style={{ flex: 1 }}>
      {/* App content */}
      <View style={{ flex: 1, backgroundColor: 'grey' }} />
      
      {/* Bottom Sheet */}
      <BottomSheet
        ref={bottomSheetRef}
        index={1}
        snapPoints={snapPoints}
      >
        <View style={{ flex: 1, alignItems: 'center' }}>
          <Text>Awesome 🎉</Text>
        </View>
      </BottomSheet>
    </View>
  );
};

Architecture

Bottom Sheet is built around several key components:

  • Core Components: BottomSheet provides the main interface with gesture handling and snap points, while BottomSheetModal offers modal presentation
  • Scrollable Integration: Seamless integration with React Native scrollable components through optimized versions that coordinate with sheet gestures
  • Hook System: Comprehensive hooks for imperative controls, animation configuration, and internal state access
  • Gesture System: Advanced gesture handling with customizable pan gestures, over-drag resistance, and keyboard interactions
  • Animation Engine: Built on React Native Reanimated v3 with configurable spring and timing animations

Capabilities

Core Bottom Sheet

Primary bottom sheet component with gesture-driven interactions, snap points, and extensive configuration options.

interface BottomSheetProps {
  index?: number;
  snapPoints?: Array<string | number> | SharedValue<Array<string | number>>;
  enableDynamicSizing?: boolean;
  enablePanDownToClose?: boolean;
  children: React.ReactNode;
  // ... extensive configuration options
}

export default function BottomSheet(props: BottomSheetProps): JSX.Element;

Bottom Sheet Component

Modal Presentation

Modal bottom sheets that overlay the entire screen with stack management and presentation controls.

interface BottomSheetModalProps<T = any> extends Omit<BottomSheetProps, 'containerHeight' | 'onClose'> {
  name?: string;
  stackBehavior?: 'push' | 'switch' | 'replace';
  enableDismissOnClose?: boolean;
  onDismiss?: () => void;
}

declare const BottomSheetModal: React.ForwardRefExoticComponent<BottomSheetModalProps>;
declare const BottomSheetModalProvider: React.FC<{ children?: React.ReactNode }>;

Modal Components

Scrollable Components

Optimized scrollable components that integrate seamlessly with bottom sheet gestures and provide proper interaction handling.

interface BottomSheetScrollableProps {
  enableFooterMarginAdjustment?: boolean;
  focusHook?: (effect: EffectCallback, deps?: DependencyList) => void;
  scrollEventsHandlersHook?: ScrollEventsHandlersHookType;
}

declare const BottomSheetScrollView: React.ForwardRefExoticComponent<BottomSheetScrollViewProps>;
declare const BottomSheetFlatList: React.ForwardRefExoticComponent<BottomSheetFlatListProps<any>>;
declare const BottomSheetSectionList: React.ForwardRefExoticComponent<BottomSheetSectionListProps<any, any>>;

Scrollable Components

Control Hooks

Hooks for imperative control of bottom sheets, accessing animated values, and managing modal presentation.

interface BottomSheetMethods {
  snapToIndex: (index: number, animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  snapToPosition: (position: number | string, animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  expand: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  collapse: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  close: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
}

interface BottomSheetVariables {
  animatedIndex: SharedValue<number>;
  animatedPosition: SharedValue<number>;
}

declare function useBottomSheet(): BottomSheetMethods & BottomSheetVariables;
declare function useBottomSheetModal(): { dismiss: (key?: string) => boolean; dismissAll: () => void };

Control Hooks

Animation Configuration

Hooks for creating and customizing animation configurations for bottom sheet movements.

declare function useBottomSheetSpringConfigs(
  configs: Omit<WithSpringConfig, 'velocity'>
): Omit<WithSpringConfig, 'velocity'>;

declare function useBottomSheetTimingConfigs(
  configs: TimingConfig
): TimingConfig;

interface TimingConfig {
  duration?: number;
  reduceMotion?: ReduceMotion;
  easing?: EasingFunction | EasingFunctionFactory;
}

Animation Configuration

UI Components

Specialized UI components including handles, backdrops, footers, and input components optimized for bottom sheet interactions.

interface BottomSheetHandleProps {
  animatedIndex: SharedValue<number>;
  animatedPosition: SharedValue<number>;
}

interface BottomSheetBackdropProps extends BottomSheetVariables {
  style?: ViewStyle;
}

declare const BottomSheetHandle: React.FC<BottomSheetHandleProps>;
declare const BottomSheetBackdrop: React.FC<BottomSheetBackdropProps>;
declare const BottomSheetTextInput: React.ForwardRefExoticComponent<TextInputProps>;

UI Components

Gesture and Event Handling

Advanced hooks for customizing gesture behavior, scroll event handling, and coordinating interactions between components.

type GestureEventsHandlersHookType = () => {
  handleOnStart: GestureEventHandlerCallbackType;
  handleOnChange: GestureEventHandlerCallbackType;
  handleOnEnd: GestureEventHandlerCallbackType;
  handleOnFinalize: GestureEventHandlerCallbackType;
};

type ScrollEventsHandlersHookType = (
  ref: React.RefObject<Scrollable>,
  contentOffsetY: SharedValue<number>
) => ScrollEventHandlers;

declare function useGestureEventsHandlersDefault(): GestureEventHandlers;
declare function useScrollEventsHandlersDefault(
  scrollableRef: RefObject<Scrollable>,
  scrollableContentOffsetY: SharedValue<number>
): ScrollEventHandlers;

Gesture and Event Handling

Types

interface BottomSheetVariables {
  animatedIndex: SharedValue<number>;
  animatedPosition: SharedValue<number>;
}

interface BottomSheetMethods {
  snapToIndex: (index: number, animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  snapToPosition: (position: number | string, animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  expand: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  collapse: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  close: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
  forceClose: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
}

interface BottomSheetModalMethods<T = any> extends BottomSheetMethods {
  present: (data?: T) => void;
  dismiss: (animationConfigs?: WithSpringConfig | WithTimingConfig) => void;
}

type Scrollable = FlatList | ScrollView | SectionList;

interface ContainerLayoutState {
  height: number;
  offset: Required<Insets>;
}

interface KeyboardState {
  target?: number;
  status: KEYBOARD_STATUS;
  height: number;
  heightWithinContainer: number;
  easing: KeyboardEventEasing;
  duration: number;
}

Utilities

/**
 * Enable internal library logging for debugging (development only)
 * @param excludeCategories - Optional categories to exclude from logging
 */
declare function enableLogging(excludeCategories?: Array<'layout' | 'effect' | 'callback'>): void;
Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/@gorhom/bottom-sheet@5.2.x
Publish Source
CLI
Badge
tessl/npm-gorhom--bottom-sheet badge