# React Native Action Sheet

> React Native action sheet with iOS-style grouped buttons and a separate Cancel, or Material and web rows with icons and descriptions. Destructive, disabled and selected actions, a useActionSheet hook to show it from a call, and the action runs after the sheet closes. Zero native code.

# ActionSheet

`ActionSheet` asks "what do you want to do with this?": a short list of actions in a [`BottomSheet`](./bottom-sheet), such as Share, Edit or Delete. The iOS design floats the actions in a rounded card with Cancel in a card of its own; Material and the web list them as rows on the sheet, with icons if you pass them.

```tsx
import { ActionSheet } from 'patine-ui';
```

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

export default function Example() {
  const [open, setOpen] = useState(false);
  const [last, setLast] = useState('Nothing yet');
  return (
    <>
      <DemoButton title="Photo options" onPress={() => setOpen(true)} />
      <Text style={{ marginTop: 12, textAlign: 'center' }}>Last action: {last}</Text>
      <ActionSheet
        open={open}
        onOpenChange={setOpen}
        title="Profile photo"
        actions={[
          { label: 'Take photo', onPress: () => setLast('Take photo') },
          { label: 'Choose from library', onPress: () => setLast('Choose from library') },
          { label: 'Remove photo', destructive: true, onPress: () => setLast('Remove photo') },
        ]}
      />
    </>
  );
}
```

## Example: message actions

A team chat: the options button on a message opens its actions. Pin and Unpin swap with the message's state, Delete is destructive, and the change shows once the sheet has closed.

```tsx live
import { useState } from 'react';
import { ActionSheet, Badge, Button, HStack, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const MESSAGES = [
  { id: 1, from: 'Priya', time: '9:12', text: 'Release notes are in the doc. Can someone check the migration part?' },
  { id: 2, from: 'Marco', time: '9:20', text: 'On it. The date-range section still says v1.' },
  { id: 3, from: 'Priya', time: '9:31', text: 'Fixed. Shipping at 11 unless anyone shouts.' },
];

export default function Example() {
  const [messages, setMessages] = useState(MESSAGES.map((m) => ({ ...m, pinned: m.id === 3 })));
  const [target, setTarget] = useState<number | null>(null);
  const [status, setStatus] = useState('');
  const message = messages.find((m) => m.id === target);
  const update = (id: number, change: object) => setMessages((all) => all.map((m) => (m.id === id ? { ...m, ...change } : m)));
  return (
    <VStack gap="sm" style={{ width: '100%', maxWidth: 420 }}>
      {messages.map((m) => (
        <HStack key={m.id} gap="sm" align="flex-start">
          <VStack gap="xs" style={{ flex: 1 }}>
            <HStack gap="sm" align="center">
              <Text weight="semibold">{m.from}</Text>
              <Text size="sm" color="textSecondary">{m.time}</Text>
              {m.pinned ? <Badge variant="secondary">Pinned</Badge> : null}
            </HStack>
            <Text>{m.text}</Text>
          </VStack>
          <Button size="icon" variant="ghost" accessibilityLabel={`Options for ${m.from}'s message`} onPress={() => setTarget(m.id)}>
            <Icon name="moreVertical" />
          </Button>
        </HStack>
      ))}
      {status ? <Text size="sm" color="textSecondary">{status}</Text> : null}
      <ActionSheet
        open={target !== null}
        onOpenChange={(open) => !open && setTarget(null)}
        title={message ? `${message.from}, ${message.time}` : undefined}
        message={message?.text}
        actions={
          message
            ? [
                { label: 'Reply', icon: <Icon name="reply" />, onPress: () => setStatus(`Replying to ${message.from}…`) },
                { label: 'Copy text', icon: <Icon name="copy" />, onPress: () => setStatus('Copied to the clipboard.') },
                {
                  label: message.pinned ? 'Unpin' : 'Pin to channel',
                  icon: <Icon name="pin" />,
                  onPress: () => update(message.id, { pinned: !message.pinned }),
                },
                {
                  label: 'Delete message',
                  icon: <Icon name="trash" />,
                  destructive: true,
                  onPress: () => {
                    setMessages((all) => all.filter((m) => m.id !== message.id));
                    setStatus('Message deleted.');
                  },
                },
              ]
            : []
        }
      />
    </VStack>
  );
}
```

## Actions

Each action is `{ label, onPress, description, icon, selected, destructive, disabled, testID }`:

- `description` adds a second line under the label.
- `icon` is any node shown before the label, such as a 24 px icon from the icon set you already use.
- `selected` marks the current choice with a ✓.
- `destructive` draws the label in the theme's `danger` colour, for Delete, Remove or Sign out.
- `disabled` greys the action out and ignores taps.

A tap closes the sheet through `onOpenChange(false)`, and the action's `onPress` runs once the sheet has finished closing. That way an action can open another sheet, a modal or the image picker: iOS shows only one modal at a time.

### Icons and descriptions

Icons suit the Material and web rows, where they line up at the start. Switch the example to Android or Web to see them as rows.

```tsx live
import { useState } from 'react';
import { ActionSheet } from 'patine-ui';
import { Icon } from '@patine-ui/icons';
import { DemoButton } from './DemoButton';

export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <DemoButton title="Share" onPress={() => setOpen(true)} />
      <ActionSheet
        open={open}
        onOpenChange={setOpen}
        title="Share “Summer trip”"
        actions={[
          { label: 'Copy link', description: 'Anyone with the link can view', icon: <Icon name="link" /> },
          { label: 'Send in a message', icon: <Icon name="messageSquare" /> },
          { label: 'Invite people', description: 'They can add photos too', icon: <Icon name="users" /> },
          { label: 'Download all', icon: <Icon name="download" />, disabled: true },
        ]}
      />
    </>
  );
}
```

### A choice with a ✓

For a short choice that applies right away, such as a sort order or video quality, mark the current one with `selected`.

```tsx live
import { useState } from 'react';
import { ActionSheet } from 'patine-ui';
import { DemoButton } from './DemoButton';

const SORTS = ['Newest', 'Oldest', 'Most liked', 'Name'];

export default function Example() {
  const [open, setOpen] = useState(false);
  const [sort, setSort] = useState('Newest');
  return (
    <>
      <DemoButton title={`Sort by: ${sort}`} onPress={() => setOpen(true)} />
      <ActionSheet
        open={open}
        onOpenChange={setOpen}
        title="Sort by"
        actions={SORTS.map((label) => ({
          label,
          selected: label === sort,
          onPress: () => setSort(label),
        }))}
      />
    </>
  );
}
```

For a longer list, or one with search, use [`Select`](./select).

## Confirm a delete

`title` names what the actions apply to; `message` adds a line under it, such as what a Delete removes. With one destructive action, the sheet is a confirmation.

```tsx live
import { useState } from 'react';
import { ActionSheet } from 'patine-ui';
import { DemoButton } from './DemoButton';

export default function Example() {
  const [open, setOpen] = useState(false);
  const [notes, setNotes] = useState(3);
  return (
    <>
      <DemoButton title={`Delete a note (${notes} left)`} onPress={() => setOpen(true)} disabled={!notes} />
      <ActionSheet
        open={open}
        onOpenChange={setOpen}
        title="Delete this note?"
        message="It's removed from all your devices."
        showCancel
        actions={[{ label: 'Delete note', destructive: true, onPress: () => setNotes((n) => n - 1) }]}
      />
    </>
  );
}
```

## Show it from a call

`useActionSheet` shows a sheet without an `open` state of your own, as `showActionSheetWithOptions` does in `@expo/react-native-action-sheet`. Render the `actionSheet` it returns once, then call `show` with the sheet's props from any handler. It needs no provider.

```tsx live
import { useState } from 'react';
import { Pressable, Text, View } from 'react-native';
import { useActionSheet } from 'patine-ui';

const FILES = ['Invoice.pdf', 'Photo.jpg', 'Notes.txt'];

export default function Example() {
  const { show, actionSheet } = useActionSheet();
  const [last, setLast] = useState('Nothing yet');
  const openMenu = (file: string) =>
    show({
      title: file,
      actions: [
        { label: 'Rename', onPress: () => setLast(`Rename ${file}`) },
        { label: 'Delete', destructive: true, onPress: () => setLast(`Delete ${file}`) },
      ],
    });
  return (
    <View style={{ gap: 8 }}>
      {FILES.map((file) => (
        <Pressable key={file} onPress={() => openMenu(file)} style={{ padding: 14, borderRadius: 12, backgroundColor: '#F4F2EE' }}>
          <Text>{file} ⋯</Text>
        </Pressable>
      ))}
      <Text style={{ textAlign: 'center' }}>Last action: {last}</Text>
      {actionSheet}
    </View>
  );
}
```

`show` takes every `ActionSheet` prop except `open`, and `onOpenChange` is optional. `hide()` closes the sheet from code.

## Cancel

The iOS design ends with a Cancel button in its own card, as iOS does. Material and web sheets don't: they close on a backdrop tap, a swipe down or Back. `showCancel` turns it on or off for any design, and `cancelLabel` renames it. Cancel, the backdrop, a swipe and Back all call `onOpenChange(false)` without running an action.

## Bottom sheet or modal

`presentation` is the same as on [`BottomSheet`](./bottom-sheet#bottom-sheet-or-modal): `'auto'` (default) is a centered modal on wide web windows and a bottom sheet everywhere else. Anything else the sheet takes, such as `bottomInset` or `onClosed`, goes in `sheetProps`. An action sheet doesn't expand to full screen (`expandable: false`), and only the Material and web designs show the grab handle; `sheetProps` can turn either back on.

## Accessibility

Each action is a button named by its label and description, marked disabled or selected, and the title is a header. On the web, arrow keys move between actions and Escape closes the sheet.

## Props

| 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: on any action, Cancel, a backdrop tap, a swipe down and Back. Set `open` to `false` here. Not called when `open` changes from your code. |
| `actions` | `ActionSheetAction[]` | **required** | The actions, top to bottom. |
| `title` | `string` | — | What the actions apply to. |
| `message` | `string` | — | A line under the title. |
| `showCancel` | `boolean` | `true` iOS / `false` Material and web | A Cancel button after the actions. |
| `cancelLabel` | `string` | `'Cancel'` | |
| `presentation` | `'auto' \| 'bottomSheet' \| 'modal'` | `'auto'` | Bottom sheet or centered modal. |
| `sheetProps` | `Partial<BottomSheetProps>` | — | Passed to the [`BottomSheet`](./bottom-sheet#api), except `open`, `onOpenChange` and `children`. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. See [Theming](../guides/theming). |
| `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. |
| `styles` | `SlotStyles<ActionSheetSlot>` | — | [Slot styles](../guides/styling): `group` (the iOS cards), `header` / `title` / `message` (the title block), `action` / `actionLabel` / `actionDescription` / `check` (each row, its label, description and ✓), `cancel` / `cancelLabel`. |
| `testID` | `string` | — | On the sheet; Cancel gets `${testID}-cancel`. |

```ts
interface ActionSheetAction {
  label: string;
  onPress?: () => void; // runs after the sheet has closed
  description?: string; // a second line under the label
  icon?: ReactNode;
  selected?: boolean; // a ✓ for the current choice
  destructive?: boolean; // theme danger colour
  disabled?: boolean;
  testID?: string;
}

const { show, hide, actionSheet } = useActionSheet();
show(options: Omit<ActionSheetProps, 'open' | 'onOpenChange'> & { onOpenChange?: (open: boolean) => void });
```

## Related

- [BottomSheet](./bottom-sheet): the sheet underneath, for your own content
- [DropdownMenu](./dropdown-menu): the same actions in a menu by the button
- [Migrate from @expo/react-native-action-sheet](../resources/migration/expo-action-sheet) or [react-native-actions-sheet](../resources/migration/actions-sheet)
