# React Native Bottom Sheet

> Animated React Native bottom sheet with drag-to-dismiss, backdrop, header, footer and keyboard avoidance. Zero native code: no Reanimated or Gesture Handler.

# 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](../guides/performance#benchmarks)).

```tsx live
import { useState } from 'react';
import { View } from 'react-native';

const DEFAULTS = { sort: 'popular', price: [0, 300] as [number, number], inStock: true, freeShipping: false };

export default function Example() {
  const [open, setOpen] = useState(false);
  const [filters, setFilters] = useState(DEFAULTS);
  const set = (patch: Partial<typeof DEFAULTS>) => setFilters((f) => ({ ...f, ...patch }));
  return (
    <>
      <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>
    </>
  );
}
```

## 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.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { BottomSheet, Button, ChipGroup, Link, Text, VStack } from 'patine-ui';

const SIZES = ['7', '7.5', '8', '8.5', '9', '9.5', '10', '10.5', '11', '12'].map((size) => ({
  label: `US ${size}`,
  value: size,
  disabled: size === '8.5' || size === '11',
}));

export default function Example() {
  const [open, setOpen] = useState(false);
  const [size, setSize] = useState<string | null>(null);
  const [added, setAdded] = useState<string | null>(null);
  const add = () => {
    setAdded(size);
    setOpen(false);
  };
  return (
    <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`).

```tsx
<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:

```tsx
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:

| | Expand | Collapse, then close |
| --- | --- | --- |
| **iOS / Android** | Drag the handle or header up | Drag it down |
| **Web** | Wheel up over the sheet, or drag the handle up | Wheel 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"`:

```tsx live
import { useState } from 'react';
import { ScrollView, Text } from 'react-native';
import { BottomSheet } from 'patine-ui';
import { DemoButton } from './DemoButton';

const comments = Array.from(
  { length: 30 },
  (_, i) => `Comment #${i + 1}: looks great!`
);

export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <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

```tsx
// 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`:

```tsx
<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

<Do preview={<>CancelFiltersApply</>}>

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

<Dont preview={<>FiltersSwipe down to close</>}>

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

<Do preview={<>{['S', 'M', 'L', 'XL'].map((s) => {s})}</>}>

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

**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.

```tsx
<BottomSheet presentation="modal" open={open} onOpenChange={close} title="Confirm">
  …
</BottomSheet>
```

## Accessibility

| | Behaviour |
| --- | --- |
| Role | A modal: VoiceOver stays inside it (`accessibilityViewIsModal`); on the web focus moves in and returns to what opened it. |
| Announced | Its `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 target | The handle and the header buttons have a 44pt touch area. |
| Reduce motion | With 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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | `false` | Show 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. |
| `children` | `ReactNode` | **Required** | Sheet content. |
| `title` | `ReactNode` | — | Header title; strings get the title style. |
| `headerLeft` | `ReactNode` | — | Left side of the header. |
| `headerRight` | `ReactNode` | — | Right side of the header. |
| `footer` | `ReactNode` | — | Content pinned below the children. |
| `presentation` | `'auto' \| 'bottomSheet' \| 'modal'` | `'auto'` | Bottom sheet or centered modal; `auto` is a modal on wide web windows. |
| `enableSwipeToClose` | `boolean` | `true` | Drag down (wheel down on the web) to dismiss (bottom sheet only). |
| `draggable` | `boolean` | `true` native / `false` web | The header row drags too, not just the handle. |
| `expandable` | `boolean` | `true` | Grow to `expandedHeight`: drag up on native, wheel up on the web. |
| `expandedHeight` | `number` | window − status bar | Expanded height: fraction (≤ 1) or px. |
| `closeOnBackdropPress` | `boolean` | `true` | Tap outside to dismiss. |
| `showHandle` | `boolean` | `true` | The grab bar at the top of a bottom sheet. Without it, only the header drags. |
| `maxHeightRatio` | `number` | `0.9` | Max height as a fraction of the window. |
| `height` | `number` | content | Fixed height: fraction (≤ 1) or px. |
| `bottomInset` | `number` | `24` iOS / `12` | Bottom padding. |
| `onOpened` | `() => void` | — | Open animation finished. |
| `onClosed` | `() => void` | — | Close animation finished (content unmounted). |
| `closeLabel` | `string` | `'Close'` | What a screen reader says for the backdrop and the ✕, which close the sheet. Translate it with the rest of your app. |
| `showCloseButton` | `boolean` | `true` | A ✕ in the header of the centered modal, unless `headerRight` takes its place. A bottom sheet has its handle instead. |
| `styles` | `SlotStyles<BottomSheetSlot>` | — | Slots below. |
| `theme` | `DeepPartial<Theme>` | — | Theme override (`sheet`, `backdrop`, `handle`, `radius.sheet`…). |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow, over the provider's: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
| `testID` | `string` | — | Test ID on the modal. |

#### Slots

| Slot | Element |
| --- | --- |
| `backdrop` | Dimmed overlay |
| `sheet` | The sheet surface |
| `handle` | Grab handle |
| `header` | Header row |
| `title` | String title text |
| `content` | Children wrapper |
| `footer` | Footer 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](../guides/i18n-rtl) and [Styling](../guides/styling).

## Related

- Migrate from [@gorhom/bottom-sheet](../resources/migration/gorhom-bottom-sheet) or [react-native-modal](../resources/migration/react-native-modal)
- [Filters sheet example](/examples/shop-filters)
