Skip to main content

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.

Loading…
<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.

Loading…
<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​

Props
side
align
arrow
presentation
<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.

Loading…
<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.

Loading…
<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.

Loading…
<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.

Loading…
<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​

DesignLook
brandA bordered card with a soft shadow, 288pt wide.
iosA rounded card with an arrow and no border, 320pt wide, like an iPad popover.
materialA raised card with large corners and no border, 280pt wide.
webA 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​

PropTypeDefaultDescription
childrenReactNoderequiredThe trigger and the content.
openboolean—Controlled open state.
defaultOpenbooleanfalseOpen on first render, uncontrolled.
triggerReactElement—Shorthand: one pressable that opens it; children are then the content.
side, align, sideOffset, arrow, presentation, accessibilityLabel, theme, designShorthand: passed to the content, as on PopoverContent.
onOpenChange(open: boolean) => void—The user opened or closed it. Not called when open changes.

PopoverTrigger​

PropTypeDefaultDescription
childrenReactElementrequiredOne pressable, such as a Button. It gets onPress (its own still runs) and aria-expanded.
styleStyleProp<ViewStyle>—The box around the trigger, which the popover lines up with.

PopoverContent​

PropTypeDefaultDescription
childrenReactNoderequiredWhat'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.
sideOffsetnumber4 (6 in brand)The gap to the trigger.
arrowbooleantrue in iOS, else falseAn arrow pointing at the trigger.
presentation'popover' | 'sheet''popover'Beside the trigger, or a bottom sheet.
accessibilityLabelstring—What screen readers call the dialog.
styleStyleProp<ViewStyle>—The panel: width, padding, colors.
themeDeepPartial<Theme>—Theme override.
design'brand' | 'ios' | 'material' | 'web' | 'native'from PatineProviderThe look to follow: brand, iOS, Material or web, or 'native' for the platform's own.
testIDstring—On the panel.

PopoverClose​

PropTypeDefaultDescription
childrenReactElementrequiredOne pressable inside the content; pressing it closes the popover.
  • 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