### Install React Navigation Dependencies

Source: https://sheet.lodev09.com/guides/navigation

Install the necessary React Navigation package before integrating TrueSheet.

```bash
npm install @react-navigation/native  

```

--------------------------------

### Basic Sheet Navigator Setup

Source: https://sheet.lodev09.com/guides/navigation

Set up the Sheet Navigator for basic usage, defining a base screen and sheet screens with options.

```javascript
import { NavigationContainer } from '@react-navigation/native';  
import {  
  createTrueSheetNavigator,  
  useTrueSheetNavigation,  
} from '@lodev09/react-native-true-sheet/navigation';  
  
const Sheet = createTrueSheetNavigator();  
  
function App() {  
  return (  
    <NavigationContainer>  
      <Sheet.Navigator>  
        {/* Base screen (first screen is the default) */}  
        <Sheet.Screen name="Main" component={MainScreen} />  
        {/* Sheet screens */}  
        <Sheet.Screen  
          name="Details"  
          component={DetailsSheet}  
          options={{ detents: ['auto', 1], cornerRadius: 16 }}  
        />  
      </Sheet.Navigator>  
    </NavigationContainer>  
  );  
}  

```

--------------------------------

### Install True Sheet with Expo

Source: https://sheet.lodev09.com/blog/release-3-0

Use this command to install True Sheet if you are working with an Expo project.

```bash
npx expo install @lodev09/react-native-true-sheet  

```

--------------------------------

### Configure Jest Mocks for TrueSheet

Source: https://sheet.lodev09.com/guides/jest

Add these mocks to your Jest setup file to enable testing of TrueSheet components. Ensure your Jest configuration includes the setup file and transforms the package correctly.

```javascript
// jest.setup.js  
  
// Main component  
jest.mock('@lodev09/react-native-true-sheet', () =>  
  require('@lodev09/react-native-true-sheet/mock')  
);

// Navigation (if using)  
jest.mock('@lodev09/react-native-true-sheet/navigation', () =>  
  require('@lodev09/react-native-true-sheet/navigation/mock')  
);

// Reanimated (if using)  
jest.mock('@lodev09/react-native-true-sheet/reanimated', () =>  
  require('@lodev09/react-native-true-sheet/reanimated/mock')  
);

```

```json
{
  "jest": {
    "setupFilesAfterEnv": ["<rootDir>/jest.setup.js"],
    "transformIgnorePatterns": [
      "node_modules/(?!(react-native|@react-native|@lodev09/react-native-true-sheet)/)"
    ]
  }
}

```

--------------------------------

### Install True Sheet v3.4.0 for Android

Source: https://sheet.lodev09.com/blog/android-stacking

Use this command to install the latest version of True Sheet, which includes the new Android dimming and stacking features.

```bash
yarn add @lodev09/react-native-true-sheet@^3.4.0  

```

--------------------------------

### Setup TrueSheetProvider for Web

Source: https://sheet.lodev09.com/guides/web

Wrap your entire application with TrueSheetProvider to enable TrueSheet functionality on the web. This component is a pass-through on native platforms.

```javascript
import { TrueSheetProvider } from '@lodev09/react-native-true-sheet'
  
const App = () => {
  return (
    <TrueSheetProvider>
      <YourApp />
    </TrueSheetProvider>
  )
}
```

--------------------------------

### Add TrueSheet Skill to Project

Source: https://sheet.lodev09.com/usage

Install the TrueSheet Usage skill into your project using the npx command. This skill provides AI coding agents with knowledge about TrueSheet.

```bash
npx skills add lodev09/react-native-true-sheet
```

--------------------------------

### Clean and Reinstall iOS Dependencies

Source: https://sheet.lodev09.com/migration

Navigate to the ios directory, remove old build artifacts and pods, then reinstall dependencies using pod install.

```bash
cd ios  
rm -rf Pods Podfile.lock build  
pod install  
cd ..  

```

--------------------------------

### Add True Sheet Package

Source: https://sheet.lodev09.com/blog/release-3-9

Install True Sheet version 3.9.0 or later using yarn.

```bash
yarn add @lodev09/react-native-true-sheet@^3.9.0  

```

--------------------------------

### Install True Sheet 3.10

Source: https://sheet.lodev09.com/blog/release-3-10

Add True Sheet version 3.10 or later to your project using Yarn.

```bash
yarn add @lodev09/react-native-true-sheet@^3.10.0
```

--------------------------------

### Install True Sheet with Yarn

Source: https://sheet.lodev09.com/blog/release-3-0

Use this command to add True Sheet version 3.0.0 or higher to your project when using Yarn.

```bash
yarn add @lodev09/react-native-true-sheet@^3.0.0  

```

--------------------------------

### Expo Router Layout Setup

Source: https://sheet.lodev09.com/guides/navigation

Integrate TrueSheet with Expo Router by using `withLayoutContext` to create a navigator. This setup allows defining sheet screens with specific options like detents and corner radius.

```typescript
app/
├── _layout.tsx          # TrueSheet navigator
├── index.tsx            # Base content
└── details.tsx          # Sheet screen

```

```typescript
// app/_layout.tsx
import { withLayoutContext } from 'expo-router';
import {
  createTrueSheetNavigator,
  type TrueSheetNavigationEventMap,
  type TrueSheetNavigationOptions,
  type TrueSheetNavigationState,
} from '@lodev09/react-native-true-sheet/navigation';
import type { ParamListBase } from '@react-navigation/native';

const { Navigator } = createTrueSheetNavigator();

const Sheet = withLayoutContext< 
  TrueSheetNavigationOptions,
  typeof Navigator,
  TrueSheetNavigationState<ParamListBase>,
  TrueSheetNavigationEventMap
>(Navigator);

export default function SheetLayout() {
  return (
    <Sheet>
      <Sheet.Screen name="index" />
      <Sheet.Screen
        name="details"
        options={{
          detents: ['auto', 1],
          cornerRadius: 16,
        }}
      />
    </Sheet>
  );
}

```

--------------------------------

### Handling TrueSheet Lifecycle Events

Source: https://sheet.lodev09.com/reference/events

This example demonstrates how to use various lifecycle events of TrueSheet, including onWillPresent, onDidPresent, onDetentChange, onWillDismiss, and onDidDismiss. It logs event details to the console for debugging and understanding the sheet's behavior.

```javascript
const App = () => {
  const handleDismiss = () => {
    console.log('Bye bye')
  }

  const handleOnWillPresent = (e: WillPresentEvent) => {
    console.log(e.nativeEvent) // { index: 0, position: 123.5, detent: 0.5 }
    console.log('Sheet is about to be presented')
  }

  const handleOnDidPresent = (e: DidPresentEvent) => {
    console.log(e.nativeEvent) // { index: 0, position: 123.5, detent: 0.5 }
  }

  const handleDetentChange = (e: DetentChangeEvent) => {
    console.log(e.nativeEvent) // { index: 1, position: 234.5, detent: 0.8 }
  }

  return (
    <View>
      <Button title="Present" onPress={() => sheet.current?.present()} />
      <TrueSheet
        ref={sheet}
        detents={[0.5, 0.8]}
        onWillPresent={handleOnWillPresent}
        onDidPresent={handleOnDidPresent}
        onDetentChange={handleDetentChange}
        onWillDismiss={handleOnWillDismiss}
        onDidDismiss={handleOnDidDismiss}
      >
        <Button title="Resize" onPress={() => sheet.current?.resize(1)} />
        <Button title="Dismiss" onPress={() => sheet.current?.dismiss(1)} />
      </TrueSheet>
    </View>
  )
}
```

--------------------------------

### Install True Sheet with Bare React Native

Source: https://sheet.lodev09.com/install

Add the True Sheet package to your Bare React Native project using Yarn. After adding the package, you must install the native dependencies for iOS.

```bash
yarn add @lodev09/react-native-true-sheet  

```

```bash
cd ios && pod install  

```

--------------------------------

### Resize TrueSheet Programmatically

Source: https://sheet.lodev09.com/guides/resizing

Define a TrueSheet and use its `resize` method to change its size. This example resizes the sheet to 69% of its available height.

```typescript
const App = () => {
  const sheet = useRef<TrueSheet>(null)

  const resize = async () => {
    // Resize to 69%
    await sheet.current?.resize(1)
    console.log('Yay, we are now at 69% 💦')
  }

  return (
    <TrueSheet name="resizing-sheet" ref={sheet} detents={['auto', 0.69, 1]}>
      <Button onPress={resize} title="Resize" />
    </TrueSheet>
  )
}
```

--------------------------------

### Define TrueSheet Component with Ref

Source: https://sheet.lodev09.com/reference/methods

Define the sheet component and provide a ref for accessing its imperative methods. This setup is necessary for using methods like `present`, `dismiss`, etc., on a specific sheet instance.

```javascript
const sheet = useRef<TrueSheet>(null)
  
return (
  <TrueSheet ref={sheet} detents={['auto', 0.8]}>
    <View />
  </TrueSheet>
)
```

--------------------------------

### Present Sheet on Screen Focus with useFocusEffect

Source: https://sheet.lodev09.com/troubleshooting

Use `useFocusEffect` to present the sheet when the screen gains focus, especially for deep linking scenarios on iOS where `initialDetentIndex` might fail on cold start.

```typescript
import { useFocusEffect } from '@react-navigation/native';
import { useCallback } from 'react';

function HomeScreen() {
  const sheet = useRef<TrueSheet>(null);
  const [didPresent, setDidPresent] = useState(false);

  useFocusEffect(
    useCallback(() => {
      if (!didPresent) {
        sheet.current?.present();
      }
    }, [didPresent])
  );

  return (
    <View>
      <TrueSheet
        ref={sheet}
        initialDetentIndex={0}
        onDidPresent={() => setDidPresent(true)}
      >
        {/* ... */}
      </TrueSheet>
    </View>
  );
}

```

--------------------------------

### Implement Safe Area Handling for Footer

Source: https://sheet.lodev09.com/guides/footer

Ensure the footer extends into the safe area by adding bottom padding, especially on mobile devices. This example uses `react-native-safe-area-context` to dynamically calculate the inset.

```javascript
import { Platform } from 'react-native';
import { useSafeAreaInsets } from 'react-native-safe-area-context';

const isIPad = Platform.OS === 'ios' && Platform.isPad;

const MyFooter = () => {
  const insets = useSafeAreaInsets();
  const bottomInset = isIPad ? 0 : insets.bottom;

  return (
    <View style={{ paddingBottom: bottomInset, backgroundColor: '#333' }}>
      <View style={{ height: 60, justifyContent: 'center', alignItems: 'center' }}>
        <Text style={{ color: '#fff' }}>Footer Content</Text>
      </View>
    </View>
  );
};

// Usage
<TrueSheet detents={['auto']} footer={<MyFooter />}>
  {/* content */}
</TrueSheet>
```

--------------------------------

### Define a Named Sheet

Source: https://sheet.lodev09.com/guides/global-methods

Define your sheet with a unique name to enable global control. This setup is typically done at the root of your application.

```jsx
const App = () => {
  return (
    <TrueSheet name="my-sheet">
      <View />
    </TrueSheet>
  )
}
```

--------------------------------

### Clean Android Build

Source: https://sheet.lodev09.com/migration

Navigate to the android directory and execute the clean command for Gradle.

```bash
cd android  
./gradlew clean  
cd ..  

```

--------------------------------

### Create and Configure Sheet Navigator

Source: https://sheet.lodev09.com/blog/sheet-navigator

Set up the Sheet Navigator with base content and sheet screens. Sheets are defined as separate screens within the navigator, allowing declarative configuration of their options.

```javascript
import { NavigationContainer } from '@react-navigation/native';
import { createTrueSheetNavigator } from '@lodev09/react-native-true-sheet/navigation';

const Sheet = createTrueSheetNavigator();

function App() {
  return (
    <NavigationContainer>
      <Sheet.Navigator>
        <Sheet.Screen name="Home" component={HomeScreen} />
        <Sheet.Screen
          name="Details"
          component={DetailsSheet}
          options={{ detents: ['auto', 1], cornerRadius: 16 }}
        />
      </Sheet.Navigator>
    </NavigationContainer>
  );
}
```

--------------------------------

### Present Sheet on Mount

Source: https://sheet.lodev09.com/guides/onmount

Use the `initialDetentIndex` prop to specify which detent the sheet should open to upon mounting. Ensure the `detents` prop is configured with the corresponding indices.

```javascript
const App = () => {
  return (
    <TrueSheet
      detents={['auto', 0.69, 1]}
      initialDetentIndex={1}
      initialDetentAnimated
    >
      <View />
    </TrueSheet>
  )
}

```

--------------------------------

### Customize Web Stacking Behavior

Source: https://sheet.lodev09.com/guides/stacking

On web, customize stacking behavior using the `stackBehavior` prop. Options include 'push', 'switch' (default), and 'replace'.

```javascript
<TrueSheet stackBehavior="push">
  <View />
</TrueSheet>

```

--------------------------------

### Rebuild and Run Expo App

Source: https://sheet.lodev09.com/guides/liquid-glass

After modifying the Expo configuration, rebuild your app using `npx expo prebuild --clean` and then run it with `npx expo run:ios` to apply the changes.

```bash
npx expo prebuild --clean
npx expo run:ios
```

--------------------------------

### Import TrueSheet Component

Source: https://sheet.lodev09.com/usage

Import the TrueSheet component from the library. This is the first step to using TrueSheet in your application.

```javascript
import { TrueSheet } from "@lodev09/react-native-true-sheet"
```

--------------------------------

### Basic TrueSheet Configuration

Source: https://sheet.lodev09.com/reference/configuration

Configure a TrueSheet with essential properties like ref, detents, and background color. The sheet contains a View component.

```jsx
<TrueSheet  
  ref={sheet}  
  detents={['auto', 0.8, 1]}  
  backgroundColor="#696969"  
  // ...  
>
  <View />  
</TrueSheet>
```

--------------------------------

### onMount

Source: https://sheet.lodev09.com/reference/events

Called when the sheet's content is mounted and ready. The sheet automatically waits for this event before presenting.

```APIDOC
## onMount

Called when the sheet's content is mounted and ready. The sheet automatically waits for this event before presenting.
```

--------------------------------

### Present Sheet Globally Using Static Method

Source: https://sheet.lodev09.com/blog/release-0-10

Import TrueSheet and use the static `present` method with the sheet's name to display it from anywhere in your application. Requires the sheet to be defined with a name.

```javascript
import { TrueSheet } from '@lodev09/react-native-true-sheet'

const SomeComponent = () => {
  const presentMySheet = () => {
    TrueSheet.present('my-sheet') // 🎉
  }

  return (
    <Button onPress={presentMySheet} title="Present My Sheet" />
  )
}

```

--------------------------------

### Add @lodev09/react-native-true-sheet with npm

Source: https://sheet.lodev09.com/migration

Use this command to add the package to your project if you are using npm.

```bash
npm install @lodev09/react-native-true-sheet@^3.0.0  

```

--------------------------------

### Component Methods: present

Source: https://sheet.lodev09.com/reference/methods

Presents the sheet. Optionally accepts a detent index and an animated flag.

```APIDOC
## present

### Description
Present the sheet. Optionally accepts a detent `index` and `animated` flag. See `detents` prop.

### Parameters
#### Path Parameters
- `index` (number) - Optional - Default: `0`
- `animated` (boolean) - Optional - Default: `true`

### Request Example
```javascript
await sheet.current?.present()

// Present without animation
await sheet.current?.present(0, false)
```
```

--------------------------------

### Sheet Navigation and Resizing

Source: https://sheet.lodev09.com/guides/navigation

Control sheet presentation and size using `useTrueSheetNavigation`. Use `navigation.resize(1)` to expand and `navigation.goBack()` to close.

```javascript
function DetailsSheet() {  
  const navigation = useTrueSheetNavigation();  
  
  return (  
    <View>  
      <Button title="Expand" onPress={() => navigation.resize(1)} />  
      <Button title="Close" onPress={() => navigation.goBack()} />  
    </View>  
  );  
}  

```

--------------------------------

### Run React Native App on iOS

Source: https://sheet.lodev09.com/migration

Execute this command to run your React Native application on an iOS simulator or device.

```bash
npx react-native run-ios  

```

--------------------------------

### Basic Header Implementation with TrueSheet

Source: https://sheet.lodev09.com/guides/header

Use the `header` prop to add a native header view. This ensures scrollable content correctly adjusts its height. Requires `TrueSheet`, `View`, `Text`, `ScrollView`, and `StyleSheet` components.

```javascript
const App = () => {
  return (
    <TrueSheet
      ref={sheet}
      header={
        <View style={styles.header}>
          <Text>My Header</Text>
        </View>
      }
    >
      <ScrollView>
        <View>{/* Your scrollable content */}</View>
      </ScrollView>
    </TrueSheet>
  )
}

const styles = StyleSheet.create({
  header: {
    padding: 16,
    borderBottomWidth: 1,
    borderBottomColor: '#eee',
  },
})
```

--------------------------------

### Presenting Sheets Globally with Static Methods

Source: https://sheet.lodev09.com/blog/release-3-0

Register named sheets using the `name` prop and present them from anywhere in your application using the static `TrueSheet.present()` method. This simplifies managing and displaying sheets across different components.

```jsx
// Register a named sheet
<TrueSheet name="my-sheet">
  {/* content */}
</TrueSheet>

// Present from anywhere
TrueSheet.present('my-sheet')
```

--------------------------------

### Check Xcode Version

Source: https://sheet.lodev09.com/troubleshooting

Verify your Xcode version using the command line. The True Sheet package requires Xcode 26.1 or later for correct background functionality.

```bash
xcodebuild -version

```

--------------------------------

### Navigate to a Sheet

Source: https://sheet.lodev09.com/blog/sheet-navigator

Navigate to a sheet screen using the standard navigation.navigate function, passing any necessary parameters.

```javascript
navigation.navigate('Details', { itemId: 123 });
```

--------------------------------

### Run React Native App on Android

Source: https://sheet.lodev09.com/migration

Execute this command to run your React Native application on an Android emulator or device.

```bash
npx react-native run-android  

```

--------------------------------

### Global Methods: present

Source: https://sheet.lodev09.com/reference/methods

Presents a sheet globally by its name. Optionally accepts a detent index and an animated flag.

```APIDOC
## present

### Description
Presents a sheet globally by its name. Optionally accepts a detent `index` and `animated` flag.

### Parameters
#### Path Parameters
- `name` (string) - Required
- `index` (number) - Optional - Default: `0`
- `animated` (boolean) - Optional - Default: `true`

### Request Example
```javascript
await TrueSheet.present('my-sheet')

// Present without animation
await TrueSheet.present('my-sheet', 0, false)
```
```

--------------------------------

### Configure Sheet Options Declaratively

Source: https://sheet.lodev09.com/blog/sheet-navigator

Customize sheet behavior and appearance by passing TrueSheet props as screen options within the Sheet.Screen component.

```javascript
<Sheet.Screen
  name="Settings"
  component={SettingsSheet}
  options={{
    detents: [0.5, 1],
    cornerRadius: 20,
    grabber: true,
    dimmedDetentIndex: 1,
    backgroundColor: '#1a1a1a',
  }}
/>
```

--------------------------------

### StackBehavior

Source: https://sheet.lodev09.com/reference/types

Defines how modals are stacked when one is presented while another is already visible. This is applicable only to the web platform.

```APIDOC
## StackBehavior

Defines the stack behavior when a modal is presented while another is visible. Web only.

### Values

- **`"push"`**: Mount the modal on top of the current one.
- **`"switch"`**: Minimize the current modal then mount the new one. This is the default behavior.
- **`"replace"`**: Dismiss the current modal then mount the new one.
- **`"none"`**: Use a regular BottomSheet instead of BottomSheetModal. Bypasses the modal stack entirely.
```

--------------------------------

### Define Sheet with Name for Global Access

Source: https://sheet.lodev09.com/blog/release-0-10

Assign a name to your TrueSheet instance to enable global access for presentation. This is the first step in using global static methods.

```javascript
const App = () => {
  return (
    <TrueSheet name="my-sheet">
      <View />
    </TrueSheet>
  )
}

```

--------------------------------

### Import Sheet Navigator Components

Source: https://sheet.lodev09.com/blog/sheet-navigator

Import the necessary components for creating and using the Sheet Navigator. Ensure you are using version 3.1.0+ of the library.

```javascript
import {
  createTrueSheetNavigator,
  useTrueSheetNavigation,
} from '@lodev09/react-native-true-sheet/navigation';

```

--------------------------------

### Present TrueSheet Globally by Name

Source: https://sheet.lodev09.com/reference/methods

Present a sheet globally by its registered name. Optionally specify the detent index and whether the animation should be enabled. Defaults to the first detent with animation.

```javascript
await TrueSheet.present('my-sheet')

// Present without animation
await TrueSheet.present('my-sheet', 0, false)
```

--------------------------------

### Wrap Existing Navigation with Sheet Navigator

Source: https://sheet.lodev09.com/guides/navigation

Wrap your root navigator with the Sheet Navigator to present sheets from any screen within your existing navigation structure.

```javascript
const Stack = createNativeStackNavigator();  
const Sheet = createTrueSheetNavigator();  
  
function RootStack() {  
  return (  
    <Stack.Navigator>  
      <Stack.Screen name="Home" component={HomeScreen} />  
      <Stack.Screen name="Profile" component={ProfileScreen} />  
    </Stack.Navigator>  
  );  
}  
  
function App() {  
  return (  
    <NavigationContainer>  
      <Sheet.Navigator>  
        <Sheet.Screen name="Root" component={RootStack} />  
        <Sheet.Screen  
          name="Details"  
          component={DetailsSheet}  
          options={{ detents: ['auto', 1], cornerRadius: 16 }}  
        />  
      </Sheet.Navigator>  
    </NavigationContainer>  
  );  
}  

```

--------------------------------

### Present TrueSheet Component

Source: https://sheet.lodev09.com/reference/methods

Present the sheet using its ref. Optionally specify the detent index and whether the animation should be enabled. Defaults to the first detent with animation.

```javascript
await sheet.current?.present()

// Present without animation
await sheet.current?.present(0, false)
```

--------------------------------

### onWillPresent

Source: https://sheet.lodev09.com/reference/events

Comes with `DetentInfoEventPayload`. This is called when the sheet is about to be presented.

```APIDOC
## onWillPresent

Comes with `DetentInfoEventPayload`.
This is called when the sheet is about to be presented.
```

--------------------------------

### Test Reanimated Integration with TrueSheet

Source: https://sheet.lodev09.com/guides/jest

Verify that the Reanimated hooks and providers for TrueSheet return the expected mocked shared values. Use `renderHook` with the `ReanimatedTrueSheetProvider` for testing.

```javascript
import {
  useReanimatedTrueSheet,
  ReanimatedTrueSheetProvider,
} from '@lodev09/react-native-true-sheet/reanimated';

it('should return mocked shared values', () => {
  const { result } = renderHook(() => useReanimatedTrueSheet(), {
    wrapper: ReanimatedTrueSheetProvider,
  });

  expect(result.current.animatedPosition.value).toBe(0);
  expect(result.current.animatedIndex.value).toBe(-1);
});

```

--------------------------------

### Adding Native Header and Footer to TrueSheet

Source: https://sheet.lodev09.com/blog/release-3-0

Implement fixed headers and footers that remain visible while content scrolls by providing components to the `header` and `footer` props. This is useful for persistent UI elements.

```jsx
<TrueSheet 
  header={<MyHeader />}
  footer={<MyFooter />}
>
  <FlatList data={items} renderItem={renderItem} />
</TrueSheet>
```

--------------------------------

### Stack Behavior for Modals

Source: https://sheet.lodev09.com/reference/types

Define how modals are presented when another is already visible. This is applicable only to the web platform.

```jsx
<TrueSheet stackBehavior="push">
  <View />
</TrueSheet>
```

--------------------------------

### Dynamic Header and Footer Updates

Source: https://sheet.lodev09.com/guides/navigation

Dynamically update sheet headers and footers using `navigation.setOptions()`. This is useful for reacting to navigation state or sheet events.

```javascript
function DetailsSheet() {  
  const navigation = useTrueSheetNavigation();  
  const [detentIndex, setDetentIndex] = useState(0);  
  
  useEffect(() => {  
    const unsubscribe = navigation.addListener('sheetDetentChange', (e) => {  
      setDetentIndex(e.data.index);  
    });  
    return unsubscribe;  
  }, [navigation]);  
  
  useEffect(() => {  
    navigation.setOptions({  
      footer: (  
        <View style={{ padding: 16 }}>  
          {detentIndex > 0 && <Button title="Collapse" onPress={() => navigation.resize(0)} />}  
          <Button title="Close" onPress={() => navigation.goBack()} />  
        </View>  
      ),  
    });  
  }, [navigation, detentIndex]);  
  
  return <View>{/* ... */}</View>;  
}  

```

--------------------------------

### onDidPresent

Source: https://sheet.lodev09.com/reference/events

Comes with `DetentInfoEventPayload`. This is called when the sheet has been presented, providing the detent `index` and `position`.

```APIDOC
## onDidPresent

Comes with `DetentInfoEventPayload`.
This is called when the sheet has been presented, providing the detent `index` and `position`.
```

--------------------------------

### Configure Stack Behavior with stackBehavior="none"

Source: https://sheet.lodev09.com/guides/web

Use stackBehavior="none" to render a non-modal sheet that does not participate in the modal stack, useful for regular BottomSheet behavior.

```javascript
<TrueSheet stackBehavior="none" detents={[0.5, 1]}>
  {/* Content */}
</TrueSheet>
```

--------------------------------

### Enable Detached Mode with detached and detachedOffset

Source: https://sheet.lodev09.com/guides/web

Render the sheet as a floating card detached from the bottom edge by using the `detached` prop. Control the spacing from the bottom with `detachedOffset`.

```javascript
<TrueSheet detached detachedOffset={24} detents={[0.5]}>
  {/* Content */}
</TrueSheet>
```

--------------------------------

### Sheet Detents Configuration

Source: https://sheet.lodev09.com/reference/types

Configure the sheet's detents using 'auto' for content-based height or fractional numbers (0-1) for percentage of screen height. The 'auto' detent is not compatible with the `scrollable` prop.

```jsx
<TrueSheet detents={['auto', 0.8, 1]}>
  <View />
</TrueSheet>
```

--------------------------------

### Navigate Directly from Sheets

Source: https://sheet.lodev09.com/guides/navigation

Navigate to other screens directly from a sheet without needing to dismiss it first. This allows for seamless transitions when presenting modals on top of sheets.

```javascript
// Navigate directly - no need to dismiss first!
navigation.navigate('SomeScreen')

```

--------------------------------

### Web Hook: useTrueSheet

Source: https://sheet.lodev09.com/reference/methods

Provides imperative methods for controlling sheets on the web platform.

```APIDOC
## useTrueSheet Hook

### Description
Provides imperative methods for controlling sheets on the web platform. Static methods are not supported on web.

### Usage
```javascript
import { useTrueSheet } from '@lodev09/react-native-true-sheet'

const { present, dismiss, dismissStack, resize, dismissAll } = useTrueSheet()

await present('my-sheet')
await dismiss('my-sheet')
await dismissAll()
```
```

--------------------------------

### Listen to Sheet Lifecycle Events

Source: https://sheet.lodev09.com/blog/sheet-navigator

Configure screenListeners on the Sheet.Navigator to react to various sheet lifecycle events such as presentation, dismissal, detent changes, and position changes.

```javascript
<Sheet.Navigator
  screenListeners={{
    sheetWillPresent: (e) => console.log('Presenting at index:', e.data.index),
    sheetDidDismiss: () => console.log('Sheet dismissed'),
    sheetDetentChange: (e) => console.log('Detent changed to:', e.data.index),
    sheetPositionChange: (e) => console.log('Position:', e.data.position),
  }}
>
```

--------------------------------

### Configure EAS Build for Xcode Version

Source: https://sheet.lodev09.com/troubleshooting

Set the `eas.json` configuration to use a build image with Xcode 26.1 or later when using EAS Build to ensure compatibility.

```json
{
  "build": {
    "production": {
      "ios": {
        "image": "latest"
      }
    },
    "development": {
      "ios": {
        "image": "latest"
      }
    }
  }
}

```

--------------------------------

### Define and Control TrueSheet with Refs

Source: https://sheet.lodev09.com/usage

Define TrueSheet within a component and attach a ref to control its presentation and dismissal. Ensure the ref is correctly typed for TrueSheet.

```javascript
export const App = () => {
  const sheet = useRef<TrueSheet>(null)

  // Present the sheet ✅
  const present = async () => {
    await sheet.current?.present()
    console.log('horray! sheet has been presented 💩')
  }

  // Dismiss the sheet ✅
  const dismiss = async () => {
    await sheet.current?.dismiss()
    console.log('Bye bye 👋')
  }

  return (
    <View>
      <Button onPress={present} title="Present" />
      <TrueSheet
        ref={sheet}
        detents={['auto', 1]}
        cornerRadius={24}
      >
        <Button onPress={dismiss} title="Dismiss" />
      </TrueSheet>
    </View>
  )
}
```

--------------------------------

### Platform-Specific Overlay Implementation

Source: https://sheet.lodev09.com/guides/overlays

Use React Native's Modal on Android and FullWindowOverlay from react-native-screens on iOS to ensure overlays appear above sheets. This approach is necessary for portal-based UI libraries that render content outside the normal component hierarchy.

```javascript
import { Platform, Modal } from 'react-native'  
import { FullWindowOverlay } from 'react-native-screens'  
  
const Overlay = Platform.select({
  ios: FullWindowOverlay,
  default: Modal,
})
  
export const App = () => {
  const [visible, setVisible] = useState(false)
  
  return (
    <>
      <TrueSheet>
        <Button title="Show Dialog" onPress={() => setVisible(true)} />
      </TrueSheet>

      <Overlay visible={visible} transparent>
        <YourDialogContent onClose={() => setVisible(false)} />
      </Overlay>
    </>
  )
}

```

--------------------------------

### Define a Custom Footer Component

Source: https://sheet.lodev09.com/guides/footer

Define a React component to be used as the footer. This component will be rendered at the bottom of the sheet.

```javascript
const SomeFooter = () => {
  return (
    <View>
      <Text>My Foot-er is Awesome.</Text>
    </View>
  )
}
```

--------------------------------

### Use ReactElement Directly as Footer

Source: https://sheet.lodev09.com/guides/footer

For optimal performance, you can pass a React Element directly to the `footer` prop instead of a component reference.

```javascript
const App = () => {
  return (
    <TrueSheet
      ref={sheet}
      footer={
        <View>
          <Text>My Foot-er is more awesome.</Text>
        </View>
      }
    >
      <View />
    </TrueSheet>
  )
}
```

--------------------------------

### Present a New Sheet While Another is Visible

Source: https://sheet.lodev09.com/guides/stacking

Simply present a new sheet using its ref. The currently visible sheet will be hidden and automatically shown again when the new sheet is dismissed. Sheets do not need a parent-child relationship.

```javascript
const presentSheet2 = async () => {
  await sheet2.current?.present() // Sheet 2 will present, Sheet 1 will be hidden
}

return (
  <>
    <TrueSheet ref={sheet1}>
      <Button onPress={presentSheet2} title="Present Sheet 2" />
      <View />
    </TrueSheet>
    <TrueSheet ref={sheet2}>
      <View />
    </TrueSheet>
  </>
)

```

--------------------------------

### Component Methods: resize

Source: https://sheet.lodev09.com/reference/methods

Resizes the sheet programmatically by index. The sheet must be presented before calling this method.

```APIDOC
## resize

### Description
Resizes the sheet programmatically by `index`. The sheet must be presented before calling this method.

### Parameters
#### Path Parameters
- `index` (number) - Required

### Request Example
```javascript
// Resize to 80%
await sheet.current?.resize(1)
```
```

--------------------------------

### Test TrueSheet Component Rendering

Source: https://sheet.lodev09.com/guides/jest

Ensure that the TrueSheet component renders correctly with its children. The mock renders TrueSheet as a View, passing all props through.

```javascript
it('should render sheet content', () => {
  const { getByText } = render(
    <TrueSheet name="test" initialDetentIndex={0}>
      <Text>Sheet Content</Text>
    </TrueSheet>
  );

  expect(getByText('Sheet Content')).toBeDefined();
});

```

--------------------------------

### Global Methods: resize

Source: https://sheet.lodev09.com/reference/methods

Resizes a sheet globally by its name. The sheet must be presented before calling this method.

```APIDOC
## resize

### Description
Resizes a sheet globally by its name. The sheet must be presented before calling this method.

### Parameters
#### Path Parameters
- `name` (string) - Required
- `index` (number) - Required

### Request Example
```javascript
// Resize to 80%
await TrueSheet.resize('my-sheet', 0.8)
```
```

--------------------------------

### GrabberOptions

Source: https://sheet.lodev09.com/reference/types

Allows customization of the appearance of the grabber (drag handle) on the TrueSheet.

```APIDOC
## GrabberOptions

Options for customizing the grabber (drag handle) appearance.

### Properties

- **`width`** (`number`): The width of the grabber pill. Default: iOS: `36`, Android: `32`
- **`height`** (`number`): The height of the grabber pill. Default: iOS: `5`, Android: `4`
- **`topMargin`** (`number`): The top margin from the sheet edge. Default: iOS: `5`, Android: `16`
- **`cornerRadius`** (`number`): The corner radius of the grabber pill. Default: `height / 2`
- **`color`** (`ColorValue`): The color of the grabber. Uses native styling when not provided.
- **`adaptive`** (`boolean`): Whether the grabber adapts to light/dark mode. Uses vibrancy on iOS and theme-based colors on Android. Default: `true`
```

--------------------------------

### Background Blur Options

Source: https://sheet.lodev09.com/reference/types

Customize the background blur effect with intensity and interaction settings. This requires `backgroundBlur` to be set.

```jsx
<TrueSheet
  backgroundBlur="dark"
  blurOptions={{
    intensity: 80,
    interaction: false,
  }}>
  <View />
</TrueSheet>
```

--------------------------------

### Inset Adjustment Configuration

Source: https://sheet.lodev09.com/reference/types

Control how the bottom safe area inset affects detent heights. Set to 'never' for precise sizing without system inset adjustments.

```jsx
<TrueSheet insetAdjustment="never">
  <View />
</TrueSheet>
```

--------------------------------

### BlurOptions

Source: https://sheet.lodev09.com/reference/types

Customizes the blur effect when `backgroundBlur` is enabled. Allows control over intensity and user interaction.

```APIDOC
## BlurOptions

Options for customizing the blur effect. Only applies when `backgroundBlur` is set.

### Properties

- **`intensity`** (`number`): The intensity of the blur effect (0-100). Default: _system default_
- **`interaction`** (`boolean`): Enables or disables user interaction on the blur view. Disabling can help with visual artifacts on iOS 18+. Default: `true`
```

--------------------------------

### Navigate to Sheets from Wrapped Navigators

Source: https://sheet.lodev09.com/blog/sheet-navigator

From any screen within a navigator wrapped by Sheet Navigator, you can navigate to a sheet using navigation.navigate.

```javascript
// From anywhere in RootStack
navigation.navigate('QuickActions');
```

--------------------------------

### Scrollable TextInput with Keyboard Offset

Source: https://sheet.lodev09.com/guides/keyboard

When using scrollable sheets, keyboard handling works out of the box. Use `keyboardScrollOffset` to add extra spacing between the focused input and the keyboard.

```javascript
<TrueSheet scrollable scrollableOptions={{ keyboardScrollOffset: 16 }}>
  <ScrollView>
    <TextInput placeholder="Input 1" />
    <TextInput placeholder="Input 2" />
    <TextInput placeholder="Input 3" />
  </ScrollView>
</TrueSheet>

```

--------------------------------

### Reanimated Integration for Position Events

Source: https://sheet.lodev09.com/guides/navigation

Enable worklet-based position events for smooth UI thread animations by setting `reanimated: true` and providing a `positionChangeHandler` worklet function.

```javascript
// In your navigator  
<Sheet.Screen  
  name="Details"  
  component={DetailsSheet}  
  options={{  
    reanimated: true,  
    positionChangeHandler: (payload) => {  
      'worklet';  
      // Access payload.position, payload.detentIndex, etc.  
      console.log(payload.position);  
    },  
  }}  
/>  

```

--------------------------------

### Customize Sheet Grabber Appearance

Source: https://sheet.lodev09.com/reference/configuration

Configure the grabber's size, margin, and color when `grabber` is enabled. This applies when using custom grabber options instead of the system default.

```jsx
<TrueSheet  
  grabber  
  grabberOptions={{
    width: 48,
    height: 6,
    topMargin: 10,
    color: '#FF0000',
  }}>
  <View />  
</TrueSheet>
```

--------------------------------

### Anchor Sheet to Left Edge

Source: https://sheet.lodev09.com/guides/side-sheets

Use the `anchor` prop set to 'left' to position the sheet along the left edge. Combine with `maxContentWidth` to control the sheet's width when anchored.

```javascript
export const App = () => {
  return (
    <TrueSheet
      detents={['auto', 1]}
      anchor="left"
      maxContentWidth={400}
    >
      <View />
    </TrueSheet>
  )
}

```

--------------------------------

### Programmatically Resize Sheets

Source: https://sheet.lodev09.com/blog/sheet-navigator

Use the useTrueSheetNavigation hook within a sheet component to access navigation methods for programmatic resizing. Call navigation.resize() with the desired detent index.

```javascript
import { useTrueSheetNavigation } from '@lodev09/react-native-true-sheet/navigation';

function DetailsSheet() {
  const navigation = useTrueSheetNavigation();

  return (
    <View>
      <Button title="Expand" onPress={() => navigation.resize(1)} />
      <Button title="Collapse" onPress={() => navigation.resize(0)} />
    </View>
  );
}
```

--------------------------------

### Wrap Existing Navigation with Sheet Navigator

Source: https://sheet.lodev09.com/blog/sheet-navigator

Integrate Sheet Navigator into an existing navigation structure by nesting it within your primary navigator. This allows presenting sheets from any screen within the wrapped navigator.

```javascript
const Stack = createNativeStackNavigator();
const Sheet = createTrueSheetNavigator();

function RootStack() {
  return (
    <Stack.Navigator>
      <Stack.Screen name="Home" component={HomeScreen} />
      <Stack.Screen name="Profile" component={ProfileScreen} />
    </Stack.Navigator>
  );
}

function App() {
  return (
    <NavigationContainer>
      <Sheet.Navigator>
        <Sheet.Screen name="Root" component={RootStack} />
        <Sheet.Screen name="QuickActions" component={QuickActionsSheet} />
        <Sheet.Screen name="Share" component={ShareSheet} />
      </Sheet.Navigator>
    </NavigationContainer>
  );
}
```

--------------------------------

### Dock Sheet to Left Edge with Anchor Prop

Source: https://sheet.lodev09.com/blog/release-3-9

Use the 'anchor' prop to dock the sheet to the left or right edge, ideal for tablet layouts. 'maxContentWidth' controls the sheet's width on larger screens.

```jsx
<TrueSheet  
  anchor="left"  
  maxContentWidth={600}  
  detents={['auto', 1]}>  
  <View />  
</TrueSheet>  

```

--------------------------------

### Test TrueSheet Static Methods with Jest

Source: https://sheet.lodev09.com/guides/jest

Verify that TrueSheet's static methods like `present` and `dismiss` are called correctly with the expected arguments. Remember to await these methods as they return Promises.

```javascript
import { TrueSheet } from '@lodev09/react-native-true-sheet';

it('should present sheet', async () => {
  await TrueSheet.present('my-sheet', 0);

  expect(TrueSheet.present).toHaveBeenCalledWith('my-sheet', 0);
});

it('should dismiss sheet', async () => {
  await TrueSheet.dismiss('my-sheet');

  expect(TrueSheet.dismiss).toHaveBeenCalledWith('my-sheet');
});

```

--------------------------------

### PositionChangeEventPayload Structure

Source: https://sheet.lodev09.com/reference/types

This object is provided with the onPositionChange event and extends DetentInfoEventPayload with realtime information.

```json
{
  index: 1.5,
  position: 123.5,
  detent: 0.5,
  realtime: true
}
```

--------------------------------

### Control Sheet Width with MaxContentWidth

Source: https://sheet.lodev09.com/blog/release-3-9

Set the 'maxContentWidth' prop to control the sheet's width on larger screens. Defaults vary by platform.

```jsx
<TrueSheet maxContentWidth={500} detents={['auto', 1]}>  
  <View />  
</TrueSheet>  

```

--------------------------------

### onPositionChange

Source: https://sheet.lodev09.com/reference/events

Comes with `PositionChangeEventPayload`. This is called continuously when the sheet's position changes during drag operations or transitions. This event fires more frequently than `onDragChange` and provides real-time position updates. The `realtime` property indicates whether the position value is real-time (e.g., during drag or animation tracking). When `realtime` is `false`, the position should be animated in JS (ReanimatedTrueSheet handles this automatically). Use this event when you need smooth, continuous position tracking for animations or visual feedback. For less frequent updates during dragging, use `onDragChange` instead.

```APIDOC
## onPositionChange

Comes with `PositionChangeEventPayload`.
This is called continuously when the sheet's position changes during drag operations or transitions. This event fires more frequently than `onDragChange` and provides real-time position updates.
The `realtime` property indicates whether the position value is real-time (e.g., during drag or animation tracking). When `realtime` is `false`, the position should be animated in JS (ReanimatedTrueSheet handles this automatically).
tip
Use this event when you need smooth, continuous position tracking for animations or visual feedback. For less frequent updates during dragging, use `onDragChange` instead.
```

--------------------------------

### Integrate Sheet Navigator with Expo Router

Source: https://sheet.lodev09.com/blog/sheet-navigator

Use withLayoutContext from expo-router to integrate Sheet Navigator with Expo Router. Define sheet options in unstable_settings within the sheet's layout file.

```javascript
// app/_layout.tsx
import { withLayoutContext } from 'expo-router';
import { createTrueSheetNavigator } from '@lodev09/react-native-true-sheet/navigation';

const { Navigator } = createTrueSheetNavigator();
export default withLayoutContext(Navigator);
```

```javascript
// app/details.tsx
export const unstable_settings = {
  options: { detents: ['auto', 1], cornerRadius: 16 },
};

export default function DetailsSheet() {
  // Sheet content
}
```

--------------------------------

### PositionChangeEventPayload

Source: https://sheet.lodev09.com/reference/types

An object that accompanies the `onPositionChange` event. It extends `DetentInfoEventPayload` and includes additional information about the real-time nature of the position change.

```APIDOC
## `PositionChangeEventPayload`

`Object` that comes with the `onPositionChange` event. Extends `DetentInfoEventPayload`.

```json
{
  "index": 1.5,
  "position": 123.5,
  "detent": 0.5,
  "realtime": true
}
```

### Properties

*   **index** (`number`) - Required - The interpolated detent index. Continuous value that smoothly transitions between detents (e.g., `0.5` means halfway between detent 0 and 1).
*   **position** (`number`) - Required - The Y position of the sheet relative to the screen.
*   **detent** (`number`) - Required - The detent value (0-1) for the nearest detent index.
*   **realtime** (`boolean`) - Required - Whether the position is a real-time value (e.g., during drag or animation tracking). When `false`, position should be animated in JS.
```

--------------------------------

### Custom Dimming Alpha with Reanimated - True Sheet

Source: https://sheet.lodev09.com/guides/dimming

Dynamically control dimming opacity based on the sheet's position using `ReanimatedTrueSheet` and `animatedPosition`. Adjust the multiplier in `useAnimatedStyle` for desired alpha.

```javascript
import { ReanimatedTrueSheet, ReanimatedTrueSheetProvider, useReanimatedTrueSheet } from '@lodev09/react-native-true-sheet/reanimated'
import Animated, { useAnimatedStyle } from 'react-native-reanimated'
import { StyleSheet } from 'react-native'

export const App = () => {
  return (
    <ReanimatedTrueSheetProvider>
      <View style={styles.container}>
        <CustomBackdrop />
        <Sheet />
      </View>
    </ReanimatedTrueSheetProvider>
  )
}

const CustomBackdrop = () => {
  const { animatedPosition } = useReanimatedTrueSheet()

  const backdropStyle = useAnimatedStyle(() => ({
    opacity: animatedPosition.value * 0.5, // Adjust multiplier for desired alpha
  }))

  return <Animated.View style={[StyleSheet.absoluteFill, styles.backdrop, backdropStyle]} />
}

const Sheet = () => {
  return (
    <ReanimatedTrueSheet
      detents={[0.25, 0.5, 1]}
      dimmed={false}
    >
      <View />
    </ReanimatedTrueSheet>
  )
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
  },
  backdrop: {
    backgroundColor: 'black',
  },
})

```

--------------------------------

### Sheet Navigator Screen Listeners

Source: https://sheet.lodev09.com/guides/navigation

Use `screenListeners` on the navigator to listen for sheet presentation and dismissal events. These listeners are called when the sheet's lifecycle events occur.

```typescript
<Sheet.Navigator  
  screenListeners={{
    sheetDidPresent: (e) => console.log('Presented:', e.data.index),
    sheetDidDismiss: () => console.log('Dismissed'),
  }}
>

```

--------------------------------

### Dismiss a Sheet

Source: https://sheet.lodev09.com/blog/sheet-navigator

Dismiss the currently presented sheet by calling navigation.goBack(), similar to navigating back from a regular screen.

```javascript
navigation.goBack();
```

--------------------------------

### onDragBegin

Source: https://sheet.lodev09.com/reference/events

Comes with `DetentInfoEventPayload`. This is called when the sheet has began dragging.

```APIDOC
## onDragBegin

Comes with `DetentInfoEventPayload`.
This is called when the sheet has began dragging.
```