Configuration

Configuration props available for TrueSheet. Extends ViewProps.

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

ref

We use ref to reference our sheet and call the imperative methods. Learn more about refs here.

detents

Array of detents you want the sheet to support. See this guide for example.

name

The name to reference this sheet. It has to be unique. You can then present this sheet globally using its name. See this guide for example.

backgroundColor

The sheet's background color. Uses the system default when not provided.

detentBackgrounds

Backgrounds matched to detents by index. Each entry is a color string or an object with either color or blur. A string such as "#18202b" is shorthand for { color: "#18202b" }. null, undefined, and missing entries inherit backgroundColor/backgroundBlur. An entry replaces the sheet background, so a color entry overrides the sheet blur.

<TrueSheet
  detents={['peek', 'auto', 1]}
  detentBackgrounds={[null, { blur: 'system-material' }, '#18202b']}
/>

The midpoint rule applies in both directions, including resize(). Presentation starts with the entry at the presented index. background and backgroundStyle remain above these effects and apply across all detents. An opaque background wrapper hides the detent backgrounds. See per-detent backgrounds for Liquid Glass limitations.

background

A custom background behind the header, content, and footer. Accepts a ReactNode. The wrapper fills the sheet, sits above the sheet background effects, and ignores touches. It does not affect content height or detent calculations.

Size the element to fill the wrapper:

<TrueSheet background={<View style={[StyleSheet.absoluteFill, { backgroundColor: '#18202b' }]} />}>
  <Text>Sheet content</Text>
</TrueSheet>

For a custom blur, see the Backgrounds guide.

backgroundStyle

Style for the background wrapper. Only backgroundColor is supported. The style works without a background element and applies across all detents.

Use an opaque color for an exact background color, including over full-screen modals. Use a translucent color to tint the glass or blur:

<TrueSheet
  backgroundBlur="system-material"
  backgroundStyle={{ backgroundColor: 'rgba(0, 122, 255, 0.25)' }}
>
  <Text>Sheet content</Text>
</TrueSheet>

backgroundBlur

The blur effect style on iOS, such as "light", "dark", or "system-material". It takes precedence over backgroundColor. Use backgroundStyle.backgroundColor to tint the blur.

For custom intensity or blur on other platforms, use a third-party blur in background.

cornerRadius

The sheet corner radius.

elevation

The elevation (shadow depth) of the sheet.

maxContentHeight

The absolute maximum height of the sheet content, regardless of detents.

maxContentWidth

The maximum width of the sheet content.

placement

Horizontal placement of the sheet. 'leading' and 'trailing' follow the layout direction (left/right in LTR, right/left in RTL).

placementOffset

The offset from the screen edge. Only applies when placement is 'leading' or 'trailing'.

dismissible

If set to false, the sheet will prevent interactive dismissal via dragging or clicking outside of it.

dismissThreshold

How far the sheet must be swiped down from its lowest detent to dismiss. The default 'half' matches iOS. Use 'short' for Compose Material3's ModalBottomSheet feel.

draggable

If set to false, the sheet will disable dragging to resize. The sheet can only be resized programmatically using the resize method.

dimmed

Specify whether the sheet background is dimmed. Set to false to allow interaction with the background components.

dimColor

The color of the dim behind the sheet.

dimOpacity

The opacity of the dim behind the sheet, from 0 to 1.

dimmedDetentIndex

The detent index that the sheet should start to dim the background.

initialDetentIndex

Initially present the sheet, after mounting, at a given detent index.

initialDetentAnimated

Specify whether the sheet should animate after mounting. Used with initialDetentIndex.

lazy

Specify whether the sheet content should mount lazily, on first presentation. Set to false to mount the content before presentation without presenting the sheet. Use this when content is not ready on the first render, then call present() after your readiness signal so auto detents measure the settled content.

grabber

Shows a native grabber (or drag handle) on the sheet.

grabberOptions

Options for customizing the grabber appearance. Only applies when grabber is true.

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

accessibilityOptions

Options for customizing (e.g. localizing) the accessibility strings announced by screen readers.

<TrueSheet
  accessibilityOptions={{
    grabberLabel: 'Poignée de déplacement',
    expandedValue: 'Développé',
    collapsedValue: 'Réduit',
  }}
>
  <View />
</TrueSheet>

header

A component that is fixed at the top of the sheet content. Useful for search bars, titles, or other header content. The header height is automatically accounted for in layout calculations. Accepts a functional Component or ReactElement. See this guide for example.

headerStyle

Style for the header container.

headerOptions

Options for customizing header behavior.

footer

A component that is pinned at the bottom of the sheet. The footer height is automatically accounted for in layout calculations. Accepts a functional Component or ReactElement. See this guide for example.

footerStyle

Style for the footer container.

footerOptions

Options for customizing footer behavior.

scrollableRef

A ref to the scrollable component (e.g. ScrollView, FlatList) rendered within the sheet content. Required for scrollable handling — nested scrolling, keyboard insets, and auto detent sizing are wired to this scrollable. See this guide for more information.

scrollableOptions

Options for customizing scrollable behavior. Applies to the scrollable provided via scrollableRef. See this guide for more information.

presentation

Controls the sheet presentation style on iPad and web (landscape/tablet).

• 'page': bottom-attached page sheet (full or readable width).
• 'form': centered floating form sheet (default form-sheet width).

'form' is absolute — maxContentWidth is ignored when set.

insetAdjustment

Controls how the bottom safe area inset affects detent heights.

detached

Renders the sheet as a detached floating card, not attached to the bottom edge.

detachedOffset

The offset from the bottom edge when detached is enabled.

style

The sheet's content style override.

Content lays out naturally by default — like a regular view or a screen. Pass flex: 1 to fill the sheet's visible height per detent.