BottomSheet

Installation

npx axiom add bottom-sheet

pnpm dlx axiom add bottom-sheet

yarn dlx axiom add bottom-sheet

bun x axiom add bottom-sheet

Also copies: portal, overlay, tappable, slot, title, icon-button.

Requires the close icon in your icon registry.

The sheet follows the keyboard with react-native-keyboard-controller. It’s a native module: rebuild your development build after installing it, and wrap your app in its KeyboardProvider:

import { KeyboardProvider } from "react-native-keyboard-controller";

<GestureHandlerRootView style={{ flex: 1 }}>
	<KeyboardProvider>
		<PortalProvider>{/* … */}</PortalProvider>
	</KeyboardProvider>
</GestureHandlerRootView>;

Installs: react-native-reanimated, react-native-worklets, react-native-gesture-handler, react-native-safe-area-context.

The sheet renders in the root PortalHost, and its gestures need GestureHandlerRootView above it. Wrap your root layout once:

import { GestureHandlerRootView } from "react-native-gesture-handler";
import { PortalHost, PortalProvider } from "@/components/core/portal";

export default function RootLayout() {
	return (
		<GestureHandlerRootView style={{ flex: 1 }}>
			<PortalProvider>
				<Stack />
				<PortalHost />
			</PortalProvider>
		</GestureHandlerRootView>
	);
}

Usage

import { BottomSheet } from "@/components/ui/bottom-sheet";

<BottomSheet.Root>
	<BottomSheet.Trigger asChild>
		<Button>Share</Button>
	</BottomSheet.Trigger>
	<BottomSheet.Content snapPoints={["50%", "90%"]}>
		<BottomSheet.Handle />
		<BottomSheet.Header title="Share" />
		{/* content */}
	</BottomSheet.Content>
</BottomSheet.Root>;

Props

BottomSheet.Root

BottomSheet.Trigger

BottomSheet.Content

BottomSheet.Handle, BottomSheet.Header, BottomSheet.ScrollView

Haptics

Pass a kind to BottomSheet.Content, usually "light", to play a haptic when the user drags the sheet onto another snap point. Opening, closing and index changes made in code play nothing: the haptic answers the finger. Nothing plays until your app connects a haptics library: see Haptics.

Use cases

Actions on an item

snapPoints={['content']}: the sheet takes the height it needs and no more.

<BottomSheet.Content detached>
	<BottomSheet.Handle />
	<FileSummary file={file} />
	<OptionItem label="Share" trailing={<Icon name="share" />} onPress={share} />
	<OptionItem label="Delete" destructive onPress={confirmDelete} />
</BottomSheet.Content>

Short form without leaving the screen

The sheet rises above the keyboard; the main button lives in footer so it stays reachable.

<BottomSheet.Content snapPoints={["content"]} keyboardBehavior="extend">
	<BottomSheet.Header
		leading={
			<Button variant="ghost" onPress={close}>
				Cancel
			</Button>
		}
		title="New list"
		trailing={
			<Button variant="ghost" disabled={!name} onPress={create}>
				Create
			</Button>
		}
	/>
	<Input autoFocus value={name} onChangeText={setName} accessibilityLabel="List name" />
</BottomSheet.Content>

Map with a draggable list

Several snap points over content that stays interactive. The list scrolls once the sheet is fully open.

<BottomSheet.Root open>
	<BottomSheet.Content
		snapPoints={[120, "45%", "90%"]}
		overlay={false}
		dismissible={false}
	>
		<BottomSheet.Handle />
		<SearchBar />
		<BottomSheet.FlatList data={places} renderItem={renderPlace} />
	</BottomSheet.Content>
</BottomSheet.Root>

Stacking

Open a sheet from inside another one and the first doesn’t just sit there under the second. It scales down and stays behind, dimmed by the new sheet’s overlay, while the new one rises in front of it.

There is nothing to install and nothing to turn on. Write two sheets and open the second one:

<BottomSheet.Root open={filtersOpen} onOpenChange={setFiltersOpen}>
	<BottomSheet.Content snapPoints={["60%"]}>
		<BottomSheet.Handle />
		<BottomSheet.Header title="Filters" />
		<OptionItem label="Sort by" value={sort} onPress={() => setSortOpen(true)} />
	</BottomSheet.Content>
</BottomSheet.Root>

<BottomSheet.Root open={sortOpen} onOpenChange={setSortOpen}>
	<BottomSheet.Content>
		<BottomSheet.Handle />
		<BottomSheet.Header title="Sort by" closeButton />
		<SortOptions value={sort} onChange={setSort} />
	</BottomSheet.Content>
</BottomSheet.Root>

Both roots sit at screen level, side by side. Nesting the second root inside the first one’s content works too, and ties their lifetimes together: closing the filters sheet unmounts the sort sheet with it.

With a single sheet open, none of this runs and nothing about the sheet changes.

The movement

Opening and closing are not mirror images of each other.

The sheet underneath only ever scales. It doesn’t move up, it doesn’t move down; it shrinks by metrics.stackScale and comes back to full size later, from where it was.

The sheet on top only ever slides. It rises into place when it opens and drops off the bottom when it closes, at full size the whole way. Nothing about it says it is part of a stack.

Both animations start on the same frame and use the same spring, so the sheet underneath is already growing back while the one above is still on its way out.

A third sheet scales the second and leaves the first where it is: depth stops counting at two, so a sheet never shrinks past stackScale².

What the top sheet takes over

Being covered isn’t only a matter of scale. A covered sheet hands over everything that can be aimed at it:

Overlays stay per sheet. The new sheet brings its own, which is what dims the one underneath and gives the recession its depth — the price is that the app behind two sheets is dimmed twice. overlay={false} on the second sheet removes that second layer, along with the dimming of the first sheet.

Leaving the stack

A sheet with stack={false} opens over the current one without scaling it. Use it when the second sheet interrupts rather than continues — a confirmation over the sheet that asked for it:

<BottomSheet.Content stack={false} detached snapPoints={["content"]}>
	<Text>Delete this list?</Text>
</BottomSheet.Content>

It still takes the drag, the backdrop and the back action while it’s on top. What it doesn’t do is touch the sheet underneath.

Dialog and Menu

A Dialog and a Menu join the same stack, with nothing to set up.

A dialog opened from a sheet pushes it back one level, like a second sheet would. A menu takes the top spot but leaves the sheet at full size: it is anchored to a trigger on that sheet, and scaling the sheet would slide the trigger out from under it. Either way, the sheet underneath hands over the drag, the touches, the back action and the screen reader until the dialog or menu closes.

When to use it

Use a sheet when the user needs to act without losing the current screen: pick an option, fill a short form, confirm details. See Mobile design guidelines.

Related

• Menu
• Dialog
• DatePicker