# React Native Popover

> An accessible React Native popover for iOS, Android and the web: opens beside its trigger on any side, flips and stays on screen, optional arrow, closes on a tap outside, Escape or Back, and moves focus in and back. Radix-style API, pure JavaScript, works in Expo Go. Use it as one element with props, or compose the parts.

# Popover

A panel that opens beside the button that opens it: a filter form, a share box, a short explanation. It opens on the side you ask for and flips to the other when there's no room, and it never leaves the window. A tap outside, Escape on the web or Android's Back closes it.

The parts follow Radix and shadcn/ui: `Popover` holds the state, `PopoverTrigger` wraps the button, `PopoverContent` is the panel and `PopoverClose` wraps a button inside it.

```tsx
import { Popover, PopoverClose, PopoverContent, PopoverTrigger } from 'patine-ui';
```

The quickest way: give `Popover` a `trigger`, and its children become the content. The content's props (`side`, `align`, `sideOffset`, `arrow`, `presentation`, `accessibilityLabel`) go on `Popover` too.

```tsx live
import { Text } from 'react-native';
import { Button, Popover } from 'patine-ui';

export default function Example() {
  return (
    <Popover trigger={<Button variant="outline">What's this?</Button>} accessibilityLabel="About sync">
      <Text>Changes sync to your other devices within a minute.</Text>
    </Popover>
  );
}
```

## Compose the parts

For full control, leave `trigger` out and compose the parts.

```tsx live
import { Button, Popover, PopoverClose, PopoverContent, PopoverTrigger, Switch, Text, VStack } from 'patine-ui';

export default function Example() {
  return (
    <Popover>
      <PopoverTrigger style={{ alignSelf: 'center' }}>
        <Button variant="outline">Filters</Button>
      </PopoverTrigger>
      <PopoverContent accessibilityLabel="Filters">
        <VStack gap="md">
          <Text weight="medium">Show</Text>
          <Switch label="Only unread" defaultChecked />
          <Switch label="Include archived" />
          <PopoverClose>
            <Button size="sm">Done</Button>
          </PopoverClose>
        </VStack>
      </PopoverContent>
    </Popover>
  );
}
```

## Example: share a document

A document's Share button: the popover holds who can open it and the link to copy, so sharing doesn't need a whole new screen.

```tsx live
import { useState } from 'react';
import { Box, Button, CopyButton, HStack, Popover, Switch, Text, VStack } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

const LINK = 'https://docs.example.com/d/q3-plan';

export default function Example() {
  const [anyone, setAnyone] = useState(false);
  return (
    <HStack justify="space-between" align="center" style={{ width: '100%', maxWidth: 480 }}>
      <VStack>
        <Text weight="semibold">Q3 plan</Text>
        <Text size="sm" color="textSecondary">{anyone ? 'Anyone with the link can view' : 'Only people you invite'}</Text>
      </VStack>
      <Popover
        trigger={
          <Button variant="outline" startIcon={<Icon name={anyone ? 'globe' : 'lock'} size="sm" />}>
            Share
          </Button>
        }
        accessibilityLabel="Share settings"
      >
        <VStack gap="md">
          <Switch label="Anyone with the link" description="They can view, not edit." checked={anyone} onCheckedChange={setAnyone} />
          <Box row gap="xs" align="center" background="surface" radius="sm" paddingX="sm">
            <Text size="sm" numberOfLines={1} style={{ flex: 1 }}>{LINK}</Text>
            <CopyButton value={LINK} accessibilityLabel="Copy link" />
          </Box>
        </VStack>
      </Popover>
    </HStack>
  );
}
```

## Where it opens

`side` is the side of the trigger it opens on: `'bottom'` (default), `'top'`, `'left'` or `'right'`. When that side doesn't have room for the panel and the opposite one has more, it opens there instead. `align` lines it up with the trigger's `'start'`, `'center'` (default) or `'end'` edge; on the top and bottom, start and end follow the layout direction, so they swap in right-to-left layouts. `sideOffset` is the gap to the trigger.

Whatever you pick, the panel is kept 8pt inside the window.

```tsx live
import { Button, HStack, Popover, PopoverContent, PopoverTrigger, Text } from 'patine-ui';

const SIDES = ['top', 'right', 'bottom', 'left'] as const;

export default function Example() {
  return (
    <HStack gap="sm" wrap style={{ justifyContent: 'center' }}>
      {SIDES.map((side) => (
        <Popover key={side}>
          <PopoverTrigger>
            <Button variant="secondary" size="sm">{side}</Button>
          </PopoverTrigger>
          <PopoverContent side={side} arrow style={{ width: 180 }}>
            <Text size="sm">Opens on the {side}, or flips when there's no room.</Text>
          </PopoverContent>
        </Popover>
      ))}
    </HStack>
  );
}
```

## Arrow

`arrow` points the panel at its trigger. The iOS design draws one by default, as iPad popovers do; the others don't. Pass `arrow` or `arrow={false}` to choose.

## Controlled

Pass `open` and `onOpenChange` to hold the state yourself. `onOpenChange` is called when the user opens or closes it (the trigger, a tap outside, Escape, Back or a `PopoverClose`), never when you change `open`.

```tsx live
import { useState } from 'react';
import { Button, HStack, Popover, PopoverContent, PopoverTrigger, Text } from 'patine-ui';

export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <HStack gap="sm" align="center" style={{ justifyContent: 'center' }}>
      <Popover open={open} onOpenChange={setOpen}>
        <PopoverTrigger>
          <Button variant="outline">What's this?</Button>
        </PopoverTrigger>
        <PopoverContent side="top" style={{ width: 220 }}>
          <Text size="sm">Your plan renews on the 1st of each month.</Text>
        </PopoverContent>
      </Popover>
      <Text color="textSecondary">{open ? 'Open' : 'Closed'}</Text>
    </HStack>
  );
}
```

## As a bottom sheet

`presentation="sheet"` opens the same content in a [`BottomSheet`](./bottom-sheet), as [`DropdownMenu`](./dropdown-menu) does. Use it on small phones, where a panel beside the trigger leaves little room for a form.

```tsx live
import { Platform } from 'react-native';
import { Button, Popover, PopoverClose, PopoverContent, PopoverTrigger, Text, VStack } from 'patine-ui';

export default function Example() {
  return (
    <Popover>
      <PopoverTrigger style={{ alignSelf: 'center' }}>
        <Button variant="outline">Share</Button>
      </PopoverTrigger>
      <PopoverContent presentation={Platform.OS === 'web' ? 'popover' : 'sheet'} accessibilityLabel="Share">
        <VStack gap="md">
          <Text>Anyone with the link can view.</Text>
          <PopoverClose>
            <Button>Copy link</Button>
          </PopoverClose>
        </VStack>
      </PopoverContent>
    </Popover>
  );
}
```

## Designs

| Design | Look |
| --- | --- |
| `brand` | A bordered card with a soft shadow, 288pt wide. |
| `ios` | A rounded card with an arrow and no border, 320pt wide, like an iPad popover. |
| `material` | A raised card with large corners and no border, 280pt wide. |
| `web` | A compact bordered card with small corners, 288pt wide. |

Set the width, padding or colors with `style`.

## Accessibility

- The trigger reports whether it's expanded (`aria-expanded`) and that it opens a dialog (`aria-haspopup`). Give it a name: a text label, or `accessibilityLabel` on an icon button.
- The content is a `dialog`; name it with `accessibilityLabel`.
- On the web, focus moves into the popover when it opens, Tab stays inside it, and focus goes back to the trigger when it closes.
- A tap outside, Escape on the web and Android's Back close it.
- With reduce motion on, it appears without sliding in.

## Props

### Popover

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | **required** | The trigger and the content. |
| `open` | `boolean` | — | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Open on first render, uncontrolled. |
| `trigger` | `ReactElement` | — | Shorthand: one pressable that opens it; `children` are then the content. |
| `side`, `align`, `sideOffset`, `arrow`, `presentation`, `accessibilityLabel`, `theme`, `design` | | | Shorthand: passed to the content, as on `PopoverContent`. |
| `onOpenChange` | `(open: boolean) => void` | — | The user opened or closed it. Not called when `open` changes. |

### PopoverTrigger

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactElement` | **required** | One pressable, such as a `Button`. It gets `onPress` (its own still runs) and `aria-expanded`. |
| `style` | `StyleProp<ViewStyle>` | — | The box around the trigger, which the popover lines up with. |

### PopoverContent

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | **required** | What's inside. |
| `side` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'bottom'` | The side of the trigger it opens on; flips when there's no room. |
| `align` | `'start' \| 'center' \| 'end'` | `'center'` | The trigger edge it lines up with. |
| `sideOffset` | `number` | `4` (`6` in brand) | The gap to the trigger. |
| `arrow` | `boolean` | `true` in iOS, else `false` | An arrow pointing at the trigger. |
| `presentation` | `'popover' \| 'sheet'` | `'popover'` | Beside the trigger, or a bottom sheet. |
| `accessibilityLabel` | `string` | — | What screen readers call the dialog. |
| `style` | `StyleProp<ViewStyle>` | — | The panel: width, padding, colors. |
| `theme` | `DeepPartial<Theme>` | — | Theme override. |
| `design` | `'brand' \| 'ios' \| 'material' \| 'web' \| 'native'` | from `PatineProvider` | The look to follow: [brand, iOS, Material or web](../guides/designs), or `'native'` for the platform's own. |
| `testID` | `string` | — | On the panel. |

### PopoverClose

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactElement` | **required** | One pressable inside the content; pressing it closes the popover. |

## Related

- [Tooltip](./tooltip): a short label on hover or long press, with nothing to press inside
- [DropdownMenu](./dropdown-menu): a list of actions from a button
- [BottomSheet](./bottom-sheet): content from the bottom of the screen
