Skip to main content

BottomSheet

BottomSheet is the React Native bottom sheet every picker sheet is built on, exported so your own content can use it: filters, menus, confirmations, forms. It slides up over a dimmed backdrop, can be dragged down to dismiss, and is built on React Native core only. The drag runs on the UI thread, so the sheet follows your finger even while JavaScript is busy (see Performance).

Import
import { BottomSheet } from 'patine-ui';
Subpath
patine-ui/sheet
Source
GitHubMarkdown for LLMs
Runs on
iOSAndroidWebFree · MIT
Behaves like
Loading…
<>
  <Button variant="outline" startIcon={<Text>⚙️</Text>} onPress={() => setOpen(true)} style={{ alignSelf: 'flex-start' }}>
    Filters
  </Button>
  <BottomSheet
    open={open}
    onOpenChange={setOpen}
    title="Filter sneakers"
    footer={
      <HStack gap="sm">
        <Button variant="outline" style={{ flex: 1 }} onPress={() => setFilters(DEFAULTS)}>Reset</Button>
        <Button style={{ flex: 2 }} onPress={() => setOpen(false)}>Show 86 results</Button>
      </HStack>
    }
  >
    <View style={{ paddingHorizontal: 16, gap: 16 }}>
      <VStack gap="xs">
        <Text weight="semibold">Sort by</Text>
        <RadioGroup
          value={filters.sort}
          onValueChange={(sort) => set({ sort })}
          aria-label="Sort by"
          options={[
            { value: 'popular', label: 'Most popular' },
            { value: 'new', label: 'Newest' },
            { value: 'price', label: 'Price: low to high' },
          ]}
        />
      </VStack>
      <Separator />
      <VStack gap="xs">
        <HStack justify="space-between">
          <Text weight="semibold">Price</Text>
          <Text color="textSecondary">${filters.price[0]} – ${filters.price[1]}</Text>
        </HStack>
        <Slider range min={0} max={300} step={10} value={filters.price} onValueChange={(price) => set({ price })} accessibilityLabel="Price" />
      </VStack>
      <Separator />
      <Switch label="In stock only" checked={filters.inStock} onCheckedChange={(inStock) => set({ inStock })} />
      <Switch label="Free shipping" description="Orders over $50" checked={filters.freeShipping} onCheckedChange={(freeShipping) => set({ freeShipping })} />
    </View>
  </BottomSheet>
</>

Try the props​

Behaves like
Props
presentation
design
<BottomSheet
open={open}
onOpenChange={setOpen}
title="Share"
draggable
>
…
</BottomSheet>

Examples​

Each example is live: edit the code and it runs.

Pick a size​

A product page's Add to bag: the sheet lists the sizes, sold-out ones are disabled, and the footer button names the size and the price.

Behaves like
Loading…
<VStack gap="sm">
  <Text weight="semibold">Trail runner GTX</Text>
  <Text color="textSecondary">Waterproof · Moss green · $129</Text>
  <Button onPress={() => setOpen(true)}>Add to bag</Button>
  {added ? <Text color="success">{`US ${added} added to your bag.`}</Text> : null}
  <BottomSheet
    open={open}
    onOpenChange={setOpen}
    title="Choose a size"
    footer={
      <Button disabled={!size} onPress={add}>
        {size ? `Add US ${size} · $129` : 'Choose a size'}
      </Button>
    }
  >
    <View style={{ paddingHorizontal: 16, gap: 12 }}>
      <ChipGroup items={SIZES} value={size} onValueChange={setSize} accessibilityLabel="Size" />
      <Text size="sm" color="textSecondary">Runs small: most people take half a size up. Greyed sizes are sold out.</Text>
      <Link onPress={() => {}}>Size guide</Link>
    </View>
  </BottomSheet>
</VStack>

Opening and closing​

BottomSheet is fully controlled, with open and onOpenChange as in Radix: render it with open and set it to false in onOpenChange, which is called with false when the user:

  • taps the backdrop (closeOnBackdropPress, default true)
  • presses the ✕ of the centered modal (showCloseButton, default true)
  • drags the sheet down past about half its height, or flicks it down; on the web, drags past about 30% of its height (max 140 px) or scrolls the wheel down over it (enableSwipeToClose, default true)
  • presses Android's back button

When open turns false, the sheet animates out and then unmounts its children. onOpened and onClosed fire when the animations finish, which is handy for focusing inputs or running work after the sheet is gone.

A filters sheet with Reset and Apply​

The header row shows when you pass title, headerLeft or headerRight. A string title is styled for you (use the title slot): centered in the iOS design, at the start in Material and on the web. A node is rendered as-is. The drag handle always drags; the header does too on native (see draggable).

<BottomSheet
open={open}
onOpenChange={close}
title="Filters"
headerLeft={<Button variant="ghost" onPress={reset}>Reset</Button>}
headerRight={<Button variant="ghost" onPress={apply}>Apply</Button>}
>
…
</BottomSheet>

Height​

  • Default: the sheet sizes to its content, up to maxHeightRatio (default 0.9) of the window.
  • height ≤ 1: a fraction of the window height (height={0.6} → 60%).
  • height > 1: pixels.

With a fixed height, the content area becomes flex: 1, so a FlatList or ScrollView inside fills it and scrolls.

bottomInset adds bottom padding for the home indicator (default 24 on iOS, 12 elsewhere). Pass your safe-area inset for pixel-perfect results:

const insets = useSafeAreaInsets();
<BottomSheet bottomInset={insets.bottom + 8} … />

On tablets and the web the sheet is centred with a maximum width of 640.

Expanding to full screen​

The sheet can grow past its content height to expandedHeight (default: the whole window below the status bar), and collapse back:

ExpandCollapse, then close
iOS / AndroidDrag the handle or header upDrag it down
WebWheel up over the sheet, or drag the handle upWheel down, or drag the handle down

Released past halfway, or with a flick, the sheet snaps to the expanded height; otherwise it settles back. A list or scroll view inside keeps the wheel until it reaches its top or bottom, then the sheet takes over.

The handle always drags. On the web the header row doesn't by default (draggable={false}), so mouse drags there still select text; pass draggable to make the whole header a drag area. expandable={false} keeps the sheet at its content height on every platform.

Try it: open the sheet, then scroll the wheel up over it (or drag the header, since this example turns draggable on). Wide web windows show a centered modal by default, so the examples here force presentation="bottomSheet":

Behaves like
Loading…
<>
  <DemoButton title="Open comments" onPress={() => setOpen(true)} />
  <BottomSheet
    open={open}
    onOpenChange={setOpen}
    title="Comments"
    presentation="bottomSheet"
    draggable
    height={0.45}
    expandedHeight={0.9}
  >
    <ScrollView contentContainerStyle={{ padding: 16, gap: 14 }}>
      {comments.map((c) => (
        <Text key={c} style={{ fontSize: 15 }}>
          {c}
        </Text>
      ))}
    </ScrollView>
  </BottomSheet>
</>

The list scrolls first; once it's back at the top, wheeling up expands the sheet, and wheeling down at the bottom collapses it, then closes it.

Configuring it​

// Expand to 85% of the window instead of full screen
<BottomSheet expandedHeight={0.85} … />

// Expand to a fixed height in px
<BottomSheet expandedHeight={600} … />

// Mouse dragging on the web too
<BottomSheet draggable … />

// No expanding: drag (or wheel) down still closes it
<BottomSheet expandable={false} … />

// Fixed at its height: no expanding, no swipe or wheel to close
<BottomSheet expandable={false} enableSwipeToClose={false} … />

Every picker sheet takes the same props through sheetProps:

<DatePickerSheet open={open} onOpenChange={close} sheetProps={{ expandedHeight: 0.8 }} … />

Keyboard​

On iOS the sheet is wrapped in a KeyboardAvoidingView, so text inputs inside stay visible above the keyboard.

In real apps​

Patine Pro screens built with it. Each opens on that screen, live, in the screens gallery.

Guidelines​

Filters
Do

Keep a visible way out. A Cancel or Done button, not only the drag down.

Filters
Swipe down to close
Don’t

Don't rely on dragging alone. Screen reader and keyboard users can't drag.

Do

Use it for a short, focused task. Pick a size, set a filter, confirm a choice.

Sheet → Sheet → Sheet
Don’t

Don't stack a sheet on a sheet. Two layers of dragging is hard to follow; replace the content instead.

Bottom sheet or modal​

presentation switches between a bottom sheet and a centered modal:

  • 'auto' (default): a modal on web windows wider than the sheet (688 px), a bottom sheet everywhere else.
  • 'bottomSheet': always slides up from the bottom, with a drag handle.
  • 'modal': always a centered dialog that fades in, with no drag handle or swipe-to-close.
<BottomSheet presentation="modal" open={open} onOpenChange={close} title="Confirm">
…
</BottomSheet>

Accessibility​

Behaviour
RoleA modal: VoiceOver stays inside it (accessibilityViewIsModal); on the web focus moves in and returns to what opened it.
AnnouncedIts title is read first. The backdrop, and the ✕ of the centered modal, are buttons named "Close" (closeLabel).
Keyboard (web)Escape closes it on the web, and Android's back button does too.
Touch targetThe handle and the header buttons have a 44pt touch area.
Reduce motionWith reduce motion on, it appears and leaves without sliding.
  • Dragging is never the only way: give a sheet with enableSwipeToClose a visible way out as well, such as Cancel in the header or footer.

API​

BottomSheet​

PropTypeDefaultDescription
openbooleanfalseShow or hide (animated). Keep it mounted and flip this.
onOpenChange(open: boolean) => void—Called with false when the user closes it: backdrop, swipe, Escape or Android back. Set open to false here. Not called when open changes from your code.
childrenReactNodeRequiredSheet content.
titleReactNode—Header title; strings get the title style.
headerLeftReactNode—Left side of the header.
headerRightReactNode—Right side of the header.
footerReactNode—Content pinned below the children.
presentation'auto' | 'bottomSheet' | 'modal''auto'Bottom sheet or centered modal; auto is a modal on wide web windows.
enableSwipeToClosebooleantrueDrag down (wheel down on the web) to dismiss (bottom sheet only).
draggablebooleantrue native / false webThe header row drags too, not just the handle.
expandablebooleantrueGrow to expandedHeight: drag up on native, wheel up on the web.
expandedHeightnumberwindow − status barExpanded height: fraction (≤ 1) or px.
closeOnBackdropPressbooleantrueTap outside to dismiss.
showHandlebooleantrueThe grab bar at the top of a bottom sheet. Without it, only the header drags.
maxHeightRationumber0.9Max height as a fraction of the window.
heightnumbercontentFixed height: fraction (≤ 1) or px.
bottomInsetnumber24 iOS / 12Bottom padding.
onOpened() => void—Open animation finished.
onClosed() => void—Close animation finished (content unmounted).
closeLabelstring'Close'What a screen reader says for the backdrop and the ✕, which close the sheet. Translate it with the rest of your app.
showCloseButtonbooleantrueA ✕ in the header of the centered modal, unless headerRight takes its place. A bottom sheet has its handle instead.
stylesSlotStyles<BottomSheetSlot>—Slots below.
themeDeepPartial<Theme>—Theme override (sheet, backdrop, handle, radius.sheet…).
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow, over the provider's: brand, iOS, Material or web, or 'native' for the platform's own.
testIDstring—Test ID on the modal.

Slots​

SlotElement
backdropDimmed overlay
sheetThe sheet surface
handleGrab handle
headerHeader row
titleString title text
contentChildren wrapper
footerFooter wrapper

Theme tokens used​

colors.sheet (background), colors.backdrop, colors.handle, radius.sheet (top corners), animation.duration.

Right to left and custom styles work the same on every component: see Internationalization and right to left and Styling.

For AI​

Give this page to an assistant as Markdown, with Copy page at the top, or the whole API in llms-full.txt.

With the Patine MCP server, it asks for get_component_docs({ name: "BottomSheet" })