BottomSheet moves to native sheets through TrueSheet with new Content, Header, Body and Footer parts, Toast is rebuilt for rapid toasts and gains maxToasts, ScrollShadow no longer needs a gradient library, and Dialog, Select and Switch fixes
HeroUI Native v1.1.0 replaces @gorhom/bottom-sheet with native sheets through @lodev09/react-native-true-sheet: the sheet presentation controller on iOS and the native bottom sheet on Android. BottomSheet is now controlled through its ref and gains Content, Header, Body and Footer parts, and presentation="bottom-sheet" in Popover, Select and Menu uses the same native sheet. This release also rebuilds the Toast core so rapid toasts stay smooth, adds maxToasts, draws ScrollShadow fades with the native backgroundImage gradient, and fixes Dialog, Select and Switch bugs.
Installation
Update to the latest version:
npm i heroui-nativeIf you use BottomSheet or presentation="bottom-sheet", swap the sheet dependency and rebuild your app (TrueSheet is a native module):
npm uninstall @gorhom/bottom-sheet
npx expo install @lodev09/react-native-true-sheetUsing AI assistants? Simply prompt "Hey Cursor, update HeroUI Native to the latest version" and your AI assistant will automatically compare versions and apply the necessary changes. Learn more about the HeroUI Native MCP Server.
Try It on Your Device
Breaking Changes
BottomSheet Uses Native Sheets
BottomSheet is now built on @lodev09/react-native-true-sheet instead of @gorhom/bottom-sheet. The sheet is opened and closed through its ref, its props move from BottomSheet.Content to BottomSheet itself, and the portal and overlay parts are gone because the sheet presents and dims itself.
Before:
const [isOpen, setIsOpen] = useState(false);
<BottomSheet isOpen={isOpen} onOpenChange={setIsOpen}>
<BottomSheet.Trigger asChild>
<Button>Open</Button>
</BottomSheet.Trigger>
<BottomSheet.Portal>
<BottomSheet.Overlay />
<BottomSheet.Content snapPoints={['40%', '80%']}>
<BottomSheet.Close />
<BottomSheet.Title>Terms of Service</BottomSheet.Title>
<BottomSheet.Description>...</BottomSheet.Description>
</BottomSheet.Content>
</BottomSheet.Portal>
</BottomSheet>;After:
const sheetRef = useRef<BottomSheetRef>(null);
<Button onPress={() => sheetRef.current?.present()}>Open</Button>
<BottomSheet ref={sheetRef} detents={[0.4, 0.8]}>
<BottomSheet.Content>
<BottomSheet.Header>
<BottomSheet.Title>Terms of Service</BottomSheet.Title>
<BottomSheet.Description>...</BottomSheet.Description>
<BottomSheet.Close />
</BottomSheet.Header>
<BottomSheet.Body>...</BottomSheet.Body>
</BottomSheet.Content>
</BottomSheet>;| Before | Now |
|---|---|
isOpen / onOpenChange / BottomSheet.Trigger | ref.present() / ref.dismiss() and onDidDismiss |
BottomSheet.Portal, BottomSheet.Overlay | Not needed: the sheet presents natively and dims (or blurs) itself |
BottomSheet.Content sheet props | Props on BottomSheet itself; className stays on Content |
snapPoints={['40%', '80%']} | detents={[0.4, 0.8]} |
enableDynamicSizing | detents={['auto']} (the default) |
enablePanDownToClose={false} | dismissible={false} |
BottomSheetScrollView / BottomSheetFlatList | ScrollView / FlatList plus scrollableRef |
BottomSheetFooter / footerComponent | <BottomSheet.Footer isSticky> or the footer prop |
useBottomSheetAwareHandlers | Removed: the sheet handles the keyboard natively |
useBottomSheet() | Removed: keep a ref to the sheet |
Migration: Replace @gorhom/bottom-sheet with @lodev09/react-native-true-sheet (^4.1.0), rebuild the app, and update each BottomSheet using the table above. See the BottomSheet migration guide.
Related PR: #543
Bottom-Sheet Presentation in Popover, Select and Menu
presentation="bottom-sheet" keeps its API (open state, triggers, item selection and contentContainerClassName work as before), but gorhom-specific props passed to the content need their TrueSheet equivalents, for example snapPoints={['35%']} becomes detents={[0.35]}. In sheet mode, usePopoverAnimation(), useSelectAnimation() and useMenuAnimation() no longer track the sheet position; call useBottomSheetAnimation() inside the content instead.
Before:
<Select.Content presentation="bottom-sheet" snapPoints={['35%']}>After:
<Select.Content presentation="bottom-sheet" detents={[0.35]}>Related PR: #543
What's New
Native BottomSheet
BottomSheet now presents as a real native sheet, above everything including native modals and formSheet screens. Dragging, the keyboard and dimming are handled natively, so the JS portal, overlay and gesture layers are gone. (#543)
Features:
- Ref methods
present(),resize(),dismiss()anddismissStack(); sheets can also be controlled bynamewithuseTrueSheet()orTrueSheet.present(name) - New compound parts
BottomSheet.Content,BottomSheet.Header,BottomSheet.BodyandBottomSheet.Footer, matchingCard;isStickyon Header or Footer pins it while the body scrolls detentsreplacessnapPoints, with'auto'(the default) sizing the sheet to its contentdimBlurblurs the screen behind the sheet instead of dimming it- Stacked sheets, with Dialog and Toast staying visible above a presented sheet
useBottomSheetAnimation()exposes live Reanimated values (position, detent, index and a 0–1progress) for animating content with the sheet- Gesture-handler components such as
Sliderwork inside sheets on Android - Sheets as routes through TrueSheet's Expo Router navigator
- The glass theme keeps the platform's own sheet material (Liquid Glass on iOS 26); other themes use the
overlaycolor - Sheets are in the accessibility tree on both platforms, and nothing covers the app's tree while no sheet is open, which fixes VoiceOver (#372) and Maestro (#353) issues with the old sheet
Usage:
import { BottomSheet, Button, type BottomSheetRef } from 'heroui-native';
import { useRef } from 'react';
export function Example() {
const sheetRef = useRef<BottomSheetRef>(null);
return (
<>
<Button onPress={() => sheetRef.current?.present()}>Open</Button>
<BottomSheet ref={sheetRef} detents={['auto', 0.9]}>
<BottomSheet.Content>
<BottomSheet.Header isSticky>
<BottomSheet.Title>Terms of Service</BottomSheet.Title>
<BottomSheet.Close />
</BottomSheet.Header>
<BottomSheet.Body>...</BottomSheet.Body>
<BottomSheet.Footer isSticky>
<Button onPress={() => sheetRef.current?.dismiss()}>Accept</Button>
</BottomSheet.Footer>
</BottomSheet.Content>
</BottomSheet>
</>
);
}For complete documentation and examples, see the BottomSheet component page.
Toast Rebuilt for Rapid Toasts
The Toast core is rebuilt around an external store with stack layout on the UI thread, so calling toast.show() many times in a row stays smooth, mostly on Android. Only the visible stack plus one toast behind it is mounted, and toasts already on screen no longer re-render when a new one arrives. The toast.show / toast.hide / useToast API is unchanged. (#544)
A new opt-in maxToasts option on the toast provider config drops the oldest toasts past a limit. With maxToasts: 1, every new toast replaces the previous one:
<HeroUINativeProvider config={{ toast: { maxToasts: 1 } }}>
{children}
</HeroUINativeProvider>ScrollShadow Without a Gradient Library
ScrollShadow now draws its fades with the native backgroundImage style (linear-gradient), so expo-linear-gradient or similar libraries are no longer needed. On React Native 0.81–0.86 it falls back to experimental_backgroundImage automatically. LinearGradientComponent is now optional and deprecated; passing it keeps the previous rendering. (#546)
<ScrollShadow>
<ScrollView>...</ScrollView>
</ScrollShadow>CloseButton Accessibility Label
CloseButton (used by BottomSheet.Close, Dialog.Close and others) is now announced as "Close" by screen readers instead of an unlabelled button. Pass aria-label to change it. (#543)
Bug Fixes
This release includes fixes for the following issues:
- Issue #369: Swipe-to-dismiss on Toast did not work on Android, and a strip of the previous toast's text showed through the front toast while it scaled. Each toast now has its own gesture root, and the covers are drawn as sibling views. (#544)
- Toast could render under the navigation bar in Android landscape. Toasts now stay inside it. (#544)
- Dialog and Select with
presentation="dialog": releasing after an upward or short downward drag made the content jump before settling. A release that doesn't dismiss now eases straight back to rest. (#545) - Select.Overlay faded out while the dialog presentation was dragged upward. The dim layer now stays during the drag. (#545)
- Issue #542: The Switch thumb could stay at the leading edge on Uniwind versions below 1.10, and an initially selected switch could briefly start on the wrong side. The static thumb inset is removed so the animation owns the position, including in RTL. (#547)
- Example app: the horizontal ScrollShadow demo rendered blank in Arabic and Hebrew. (#548)
Related PRs:
Dependencies
- @lodev09/react-native-true-sheet
^4.1.0is a new optional peer dependency, required forBottomSheetand thepresentation="bottom-sheet"mode of Popover, Select and Menu. (#543) - @gorhom/bottom-sheet is removed as an optional peer dependency. (#543)
Updated Documentation
The following documentation pages have been updated to reflect the changes in this release:
- Quick Start — Optional dependency changed to
@lodev09/react-native-true-sheet - Provider —
maxToastsoption and TrueSheet as the raw provider's optional dependency - BottomSheet — Rewritten for native sheets, new parts, detents, blur, stacking, navigation and migration guide
- Toast —
maxToastsand notes on showing many toasts - ScrollShadow — Built-in gradient, React Native version support and
LinearGradientComponentdeprecation - Select — Bottom-sheet presentation uses TrueSheet; dialog drag fix
- Popover — Bottom-sheet presentation uses TrueSheet
- Menu — Bottom-sheet presentation uses TrueSheet
- Input — No keyboard handlers needed inside BottomSheet
- InputOTP — No keyboard handlers needed inside BottomSheet
- CloseButton — Default
aria-label="Close" - Dialog — Fixed: swipe-up release settles without jumping
- Switch — Fixed: thumb position on older Uniwind and RTL
Links
Contributors
Thanks to everyone who contributed to this release!