Sheet

Sheet presents draggable content at configurable snap points and can host adaptive content from other overlay components.

Sheet is a bottom panel for mobile-friendly dialogs and action menus. It supports drag-to-dismiss, multiple snap points, and automatically stacks above other content.

Installation

Sheet is already installed in tamagui, or you can install it independently:

yarn
npm
bun
pnpm
Copy
yarn add @tamagui/sheet

Anatomy

// copy-paste: these skins import from files you own. copy each registry item
// below into your app, then adjust the relative import paths to fit.
//   components/tamagui/Sheet.tsx (registry item "sheet")
// npm dependencies: @tamagui/core @tamagui/sheet
import { Sheet } from "../components/tamagui/Sheet"; // or '@tamagui/sheet'
export default () => <Sheet>
    <Sheet.Overlay />
    <Sheet.Handle />
    <Sheet.Container>
      <Sheet.Background />
      {/* ...inner contents */}
    </Sheet.Container>
  </Sheet>;
Copy

API reference

Contains every component for the sheet.

Displays behind the sheet content. Extends YStack.

Sheet.Overlay must be a direct child of Sheet. It renders outside the animated content region so it stays fixed while the container moves.

In v3 the sheet no longer fades anything for you. Sheet.Overlay has no baked-in opacity, so you drive its fade yourself. See Overlay fades for the two supported patterns.

Contains the sheet content and layout props. Extends YStack.

The themed sheet surface. Extends YStack.

Place it as the first child of Sheet.Container. By default it fills the container and extends past the bottom edge so spring overshoot does not reveal the page below the sheet. Put visual surface props like bg, borderRadius, and shadow* on Sheet.Background; keep layout props like padding, gap, and maxHeight on Sheet.Container.

Shows a handle above the container by default. On tap, it will cycle between snapPoints, but this can be overridden with onPress.

Extends XStack.

In v3 the Handle ships no opacity of its own. The idle dim and the fade-in on open are aesthetics, so they live in the copied skin rather than the behavior package. Set opacity (and an open-driven opacity if you want it) on your own Sheet.Handle.

Allows scrolling within Sheet. Extends ScrollView.

Sheet.useAnimatedPosition

Sheet.useAnimatedPosition() returns the sheet’s live animated position so you can drive effects that track the drag on the UI thread. Call it inside a Sheet; it throws with a clear message outside that scope.

const { value, screenSize, frameSize, snapOffsets, minY } =
  Sheet.useAnimatedPosition()
Copy

• value is the exact UniversalAnimatedNumber driving the frame’s translateY, in px from the top of the screen. Feed it to useAnimatedNumberStyle.
• screenSize is the height of the viewport the sheet positions against.
• frameSize is the measured height of the sheet frame.
• snapOffsets are the resolved translateY positions, in the same order as snapPoints.
• minY is the top-most (fully open) position.

These are enough to compute any progress mapping inside a getStyle worklet. There is no separate derived progress value; the recipe lives in docs and the canonical skin.

Sheet.useAnimatedPosition() and the Sheet onTransition callback are available on Tamagui’s custom Sheet. The native iOS system sheet selected by the native prop is driven by UIKit, which does not expose a continuous position. Remove the native prop when you need position-linked effects or transition lifecycle events.

Overlay fades

The sheet does not fade anything for you, so an overlay fade is your code. There are two supported patterns.

1. Presence fade (animates on open and close only). Put enter/exit styles on Sheet.Overlay:

<Sheet.Overlay
  transition="quick"
  opacity="0.5 enter:0 exit:0"
/>
Copy

2. Drag-linked fade (tracks the finger). Read the animated position and map it to opacity with useAnimatedNumberStyle:

// copy-paste: these skins import from files you own. copy each registry item
// below into your app, then adjust the relative import paths to fit.
//   components/tamagui/Sheet.tsx (registry item "sheet")
// npm dependencies: @tamagui/core @tamagui/sheet
import type { Animated } from 'react-native';
import { View as TamaguiView, useAnimationDriver, useAnimatedNumberStyle } from 'tamagui';

// drag-linked overlay fade built entirely on the public hooks:
// Sheet.useAnimatedPosition() gives the live translateY, useAnimatedNumberStyle
// maps it to an opacity worklet. rendered through the driver's animated view so
// it works on every driver (css re-renders + DOM transition, motion/reanimated
// run on their own value).
import { Sheet } from "../components/tamagui/Sheet";
function DragLinkedBackdrop() {
  const animationDriver = useAnimationDriver();
  const AnimatedView = (animationDriver.View ?? TamaguiView) as typeof Animated.View;
  const {
    value,
    screenSize
  } = Sheet.useAnimatedPosition();
  const style = useAnimatedNumberStyle(value, (y: number) => {
    'worklet';

    return {
      opacity: Math.max(0, 0.6 * (1 - y / screenSize))
    };
  });
  return <AnimatedView transition="quick" style={[{
    position: 'absolute',
    top: 0,
    left: 0,
    right: 0,
    bottom: 0,
    backgroundColor: '#000'
  }, style]} />;
}
<Sheet.Overlay backgroundColor="transparent">
  <DragLinkedBackdrop />
</Sheet.Overlay>;
Copy

Keep Sheet.Overlay as the direct child of Sheet, then render the hook-driven backdrop inside it. The driver’s animated view makes the worklet-driven style apply on every driver.

Native system renderers

Register a renderer at app startup to use system presentation with <Sheet native>. Without a registered renderer, Sheet uses its custom implementation. Tamagui owns open and position state, context, Adapt, and the lifetime of one content tree. The renderer owns platform presentation, authored detents, gestures, keyboard handling, and physical dismissal.

import { setupNativeSheet, type NativeSheetRendererProps } from '@tamagui/sheet'

setupNativeSheet('ios', NativeSheetRenderer)
Copy

NativeSheetRendererProps supplies the resolved open value, onOpenChange, position, onPositionChange, and normalized snapPoints. A point is { type: 'percent', value: number }, { type: 'height', value: number }, or { type: 'fit' }. A dismissal-only bottom point is removed before forwarding. The other Sheet props, content, and host ref reach the renderer unchanged.

Report interaction requests through onOpenChange and onPositionChange. Controlled parents may decline either request; continue presenting their accepted values. Call onDismiss only after the original presentation is physically removed following an accepted close. A reopen interrupts that completion. Tamagui then releases Adapt presence and, when requested, unmounts hidden children. Do not mount a second copy of the content beside the native presentation.

Render children once inside the platform host. Sheet.Container measures content without custom sheet positioning, Sheet.ScrollView forwards to the native React Native ScrollView, and the system supplies the background, overlay, and grabber. Sheet.Background, Sheet.Overlay, and Sheet.Handle render nothing in this mode. Their styles and press handlers do not customize the system chrome. Use the renderer’s presentation callbacks for dismissal policy.

The registration accepts a React component. An imperative implementation keeps a controller ref inside that component and drives its presentation methods from the resolved open value. Use a layout effect when these commands synchronize the host’s controlled value, so its acknowledgment observes the parent’s accepted state. Forward interaction requests and physical completion separately. Preserve the native library’s content container and lazy mounting behavior, and check parent-declined close and reopen during dismissal against its actual events. The previous setupNativeSheet('ios', modalModule) object registration is replaced by this component contract; no modal dependency is built into Tamagui.

Native renderers decide which Sheet options their platform can represent. Reject unsupported combinations before presenting. A native iOS system sheet does not expose continuous animated position or custom transition events. moveOnKeyboardChange does not install Tamagui’s custom keyboard driver in a native renderer; its host handles the keyboard. Keep native off for custom sheet animation and gesture behavior.

Native gesture handler integration

For the best gesture experience on iOS and Android, Sheet supports optional integration with react-native-gesture-handler. This provides:

• Smooth scroll-to-drag handoffs - transition between scrolling content and dragging the sheet
• No gesture conflicts - Sheet and ScrollView gestures coordinate properly
• Native-quality feel - matches the behavior of system sheets

Setup

1. Install react-native-gesture-handler:

yarn
npm
bun
pnpm
Copy
yarn add react-native-gesture-handler

1. Add the setup import to your app entry point (before any Tamagui imports):

// App.tsx or index.js
import '@tamagui/native/setup-gesture-handler'
import { GestureHandlerRootView } from 'react-native-gesture-handler'

export default function App() {
  return (
    <GestureHandlerRootView style={{ flex: 1 }}>{/* Your app */}</GestureHandlerRootView>
  )
}
Copy

That’s it! Sheet will automatically detect and use the native gesture handler when available.

Using Sheet.ScrollView

When using scrollable content inside a Sheet, use Sheet.ScrollView for proper gesture coordination:

<Sheet>
  <Sheet.Handle />
  <Sheet.Container>
    <Sheet.Background />
    <Sheet.ScrollView>{/* Scrollable content */}</Sheet.ScrollView>
  </Sheet.Container>
</Sheet>
Copy

This ensures:

• Scrolling up at the top of content works naturally
• Dragging down when scroll is at top drags the sheet
• Direction changes mid-gesture work smoothly

Without gesture handler

If you don’t set up react-native-gesture-handler, Sheet falls back to React Native’s built-in PanResponder. This works well for basic use cases but has some limitations on iOS where scroll and pan gestures can occasionally conflict.

Notes

A fully-closed sheet is hidden with display: 'none' rather than by fading to transparent. Use disableHideWhenClosed if you need the closed wrapper to stay laid out. pointerEvents still gates interaction while closed, and unmountChildrenWhenHidden keys off the same closed state.

For Android you need to manually re-propagate any context when using modal. This is because React Native doesn’t support portals yet.