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.
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.
<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.
<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>
Try the props
sidealignarrowpresentation<PopoverContent accessibilityLabel="Details">
…
</PopoverContent>
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.
<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.
<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.
<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, as DropdownMenu does. Use it on small phones, where a panel beside the trigger leaves little room for a form.
<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, oraccessibilityLabelon an icon button. - The content is a
dialog; name it withaccessibilityLabel. - 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, 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: a short label on hover or long press, with nothing to press inside
- DropdownMenu: a list of actions from a button
- BottomSheet: content from the bottom of the screen