技能檔案

TrueSheet Consumer Guide

Name: TrueSheet Consumer Guide
Author: lodev09

Consumer-side guide for integrating @lodev09/react-native-true-sheet into a React Native app. Use this skill whenever the user wants to add, configure, control, or debug a bottom sheet using TrueSheet — including ref-based sheets, named global sheets, web support with TrueSheetProvider/useTrueSheet, React Navigation or Expo Router sheet flows, Reanimated-driven animations, scrolling content, stacking, headers/footers, detents, side sheets, keyboard handling, dimming, liquid glass, and Jest testing. Also use when the user is migrating from v2 to v3, troubleshooting layout or gesture issues, or asking about any TrueSheet prop, event, or method — even if they don't mention "TrueSheet" by name but describe a bottom sheet in a React Native context.

lodev091,845 星標2026年3月31日

職業
分類: Frontend

技能內容

Use this skill to produce correct, idiomatic code for apps that consume @lodev09/react-native-true-sheet. It covers choosing the right integration pattern, applying the public API correctly, and avoiding platform-specific pitfalls.

Quick Start

The simplest sheet: a ref, a button, and some content.

import { useRef } from 'react'
import { Button, Text, View } from 'react-native'
import { TrueSheet } from '@lodev09/react-native-true-sheet'

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

  return (
    <View>
      <Button title="Open" onPress={() => sheet.current?.present()} />
      <TrueSheet ref={sheet} detents={['auto']} cornerRadius={24} grabber>
        <View style={{ padding: 16 }}>
          <Text>Hello from the sheet</Text>
          <Button title="Close" onPress={() => sheet.current?.dismiss()} />
        </View>
      </TrueSheet>
    </View>
  )
}

Choose the Right Control Pattern

Pick one based on where the trigger lives relative to the sheet and which platforms you target.

相關技能

TrueSheet Consumer Guide | Skills Pool

技能檔案

TrueSheet Consumer Guide

lodev091,845 星標2026年3月31日

職業
分類: Frontend

技能內容

Quick Start

The simplest sheet: a ref, a button, and some content.

import { useRef } from 'react'
import { Button, Text, View } from 'react-native'
import { TrueSheet } from '@lodev09/react-native-true-sheet'

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

  return (
    <View>
      <Button title="Open" onPress={() => sheet.current?.present()} />
      <TrueSheet ref={sheet} detents={['auto']} cornerRadius={24} grabber>
        <View style={{ padding: 16 }}>
          <Text>Hello from the sheet</Text>
          <Button title="Close" onPress={() => sheet.current?.dismiss()} />
        </View>
      </TrueSheet>
    </View>
  )
}

Choose the Right Control Pattern

Pick one based on where the trigger lives relative to the sheet and which platforms you target.

相關技能

Pattern	When to use	Platform
Ref	Trigger and sheet in the same component	All
Named + global methods	Trigger is far from the sheet (different screen, deep in tree)	Native only
`TrueSheetProvider` + `useTrueSheet()`	Web support needed, or you want hook-based control	All (required on web)
`createTrueSheetNavigator()`	Sheets are part of a navigation flow	All
`ReanimatedTrueSheet`	You need animated values synced to sheet position	All

// Somewhere in the tree
<TrueSheet name="profile" detents={['auto', 1]}>
  <ProfileContent />
</TrueSheet>

// Anywhere else (native only)
await TrueSheet.present('profile')
await TrueSheet.dismiss('profile')
await TrueSheet.resize('profile', 1)
await TrueSheet.dismissAll()

import { TrueSheet, TrueSheetProvider, useTrueSheet } from '@lodev09/react-native-true-sheet'

function Toolbar() {
  const { present, dismiss } = useTrueSheet()
  return <Button title="Open" onPress={() => present('settings')} />
}

export function App() {
  return (
    <TrueSheetProvider>
      <Toolbar />
      <TrueSheet name="settings" detents={[0.5, 1]}>
        <SettingsContent />
      </TrueSheet>
    </TrueSheetProvider>
  )
}

// Content-sized sheet
<TrueSheet detents={['auto']} />

// Half and full screen
<TrueSheet detents={[0.5, 1]} />

// Three stops: peek, half, full
<TrueSheet detents={[0.25, 0.5, 1]} />

<TrueSheet detents={[0.5, 1]} scrollable cornerRadius={24} grabber>
  <ScrollView>
    {items.map(item => <ItemRow key={item.id} item={item} />)}
  </ScrollView>
</TrueSheet>

<TrueSheet
  detents={[0.5, 1]}
  scrollable
  header={
    <View style={{ padding: 16 }}>
      <Text style={{ fontSize: 18, fontWeight: 'bold' }}>Title</Text>
    </View>
  }
  footer={<BottomActions />}
>
  <ScrollView>{/* ... */}</ScrollView>
</TrueSheet>

<TrueSheet
  ref={sheet}
  detents={['auto']}
  dismissible={false}
  draggable={false}
  dimmed
  grabber={false}
>
  <View style={{ padding: 24 }}>
    <Text>Are you sure?</Text>
    <Button title="Confirm" onPress={handleConfirm} />
    <Button title="Cancel" onPress={() => sheet.current?.dismiss()} />
  </View>
</TrueSheet>

<TrueSheet detents={['auto']} backgroundBlur="system-material">
  <View style={{ padding: 16 }}>
    <Text>Blurred sheet</Text>
  </View>
</TrueSheet>

<TrueSheet detents={['auto', 1]} initialDetentIndex={0} initialDetentAnimated>
  <WelcomeContent />
</TrueSheet>

// No dimming (allows background interaction)
<TrueSheet dimmed={false} detents={['auto']} />

// Dim only above a certain detent
<TrueSheet detents={['auto', 0.7, 1]} dimmedDetentIndex={1} />

const sheet = useRef<TrueSheet>(null)

// detents={[0.3, 0.6, 1]}
await sheet.current?.resize(2) // expands to full (index 2)

Max 3 detents, sorted smallest → largest.
Never 'auto' + scrollable — they're incompatible.
resize() takes an index, not a fraction. resize(1) means "go to the second detent."
Sheet names must be unique across your entire app.
Static methods are native-only — use useTrueSheet() on web.
Don't use autoFocus on TextInputs inside sheets. Focus in onDidPresent instead:
```
<TrueSheet onDidPresent={() => inputRef.current?.focus()}>
```
Use flexGrow: 1 (not flex: 1) inside GestureHandlerRootView on Android.
Dismiss sheets before closing Modals on iOS — React Native has a bug where dismissing a Modal while a sheet is visible causes a blank screen.
Use header/footer props for fixed chrome — don't reach for absolute positioning.
Liquid Glass is automatic on iOS 26+. Set backgroundColor to disable it per-sheet, or add UIDesignRequiresCompatibility to Info.plist to disable app-wide.

Feature	iOS	Android	Web
`'auto'` detent	iOS 16+	Yes	Yes
`backgroundBlur`	Yes	No	No
Liquid Glass	iOS 26+	No	No
Static global methods	Yes	Yes	No (use provider)
`scrollable`	Yes	Yes	No (use `BottomSheetScrollView`)
`anchor` / side sheets	System-controlled margins	`anchorOffset` prop	`anchorOffset` prop
`pageSizing` (iPad)	iOS 17+	N/A	N/A
`detached` mode	No	No	Yes
`stackBehavior`	N/A	N/A	`push` / `switch` / `replace`
Edge-to-edge	N/A	Auto-detected	N/A
Keyboard handling	Built-in	Built-in	N/A

Event	When it fires	Payload
`onMount`	Content is mounted and ready	—
`onDidPresent`	Sheet finished presenting	`{ index, position, detent }`
`onDidDismiss`	Sheet finished dismissing	—
`onDetentChange`	User dragged or `resize()` changed the detent	`{ index, position, detent }`
`onPositionChange`	Continuous position updates during drag/animation	`{ index, position, detent, realtime }`

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

Reference	What's inside
Configuration	Every prop with type, default, platform support, and notes
API	Complete events and methods reference with payload types
Advanced Patterns	Navigation, Reanimated, Web, Side sheets, Liquid Glass, Jest mocking, Migration v2→v3
Troubleshooting	Common issues and fixes by platform

Value	Meaning
`'auto'`	Size to fit the content (iOS 16+, Android, Web)
`0` – `1`	Fraction of the screen height

TrueSheet Consumer Guide

Quick Start

Choose the Right Control Pattern

TrueSheet Consumer Guide

Quick Start

Choose the Right Control Pattern

Ref-based

Named sheet with global methods (native only)

Web control with provider

Navigation (React Navigation / Expo Router)

Reanimated

Detents

Common Recipes

Scrollable content

Fixed header and footer

Non-dismissible confirmation

iOS blur background

Present on mount

Dimming control

Resize programmatically

Rules That Save Debugging Time

Platform Differences at a Glance

Events

Methods

Stacking Sheets

Deep-Dive References

Extract Errors

Frontend Patterns

Coding Standards

Coding Standards

Coding Standards

Frontend Patterns