feat: Add lazy prop to control mounting content before presentation

[maxlapides]

Summary

Add a JS-only lazy prop (default true). Setting lazy={false} mounts sheet children while the sheet remains unpresented. Keep the existing lazy behavior by default, begin rendering when lazy changes to false, preserve mounted content when it changes back to true, and keep non-lazy content mounted across dismissals. Do not forward the prop to the native component.

Without this option, a sheet using detents={['auto']} cannot mount its content before present(). Content that starts with a Suspense fallback, asynchronous loading state, or skeleton can therefore present at the placeholder height and visibly resize when the final content arrives.

Use lazy={false} to mount content early, wait for the app's readiness signal such as Suspense resolution, loaded data, or settled onLayout, and then call present(). This lets the auto detent measure settled React Native content before the presentation animation begins.

Document the new prop and its measurement limitation, add its public type, and cover the mounting and presentation lifecycle in unit tests.

Content that requires window attachment to measure, such as SwiftUI-hosted views rendered through expo-ui, still measures only during presentation. React Native/Yoga content was verified to lay out fully while unpresented in a production React Native app on an iOS 26 simulator.

Note

Originally proposed as a prewarm prop; renamed to lazy={false} per maintainer feedback.

Type of Change

• Bug fix
• New feature
• Breaking change
• Documentation update

Test Plan

• yarn lint
• yarn typecheck
• yarn test — 69 tests pass
• Verify the default lazy behavior remains unchanged
• Verify lazy={false} renders children while unpresented and when set after mount
• Verify re-enabling lazy and dismissing a non-lazy sheet preserve mounted children
• Verify present() on a non-lazy sheet skips the additional mount wait
• Verify lazy is not forwarded to the native component
• Verify React Native/Yoga content lays out while unpresented on an iOS 26 simulator

Screenshots / Videos

N/A — this changes when hidden sheet content mounts and does not introduce a visible UI change.

Checklist

• I tested on iOS
• I tested on Android
• I tested on Web
• I updated the documentation (if needed)
• I added a changelog entry (if needed)

[vercel]

@maxlapides is attempting to deploy a commit to the lodev09 Team on Vercel.

A member of the Team first needs to authorize it.

[lodev09]

@maxlapides can we just name this to lazy={false} instead? I think that's more clear

[maxlapides]

Yes, good idea @lodev09! I renamed it to lazy :)

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
react-native-true-sheet	Ready	Preview	Aug 25, 2026 10:29pm