Design System

A Popover is essentially an interactive Tooltip for displaying an overlay anchored to a particular element. It can set up to open automatically using a trigger element that also serves as its anchor point, or it can be opened manually positioned relative to an anchor element.

React

import { Popover } from '@hoverinc/design-system-react-web';

Basic usage

It is used to display contextual information to the user, and should be paired with a clickable trigger element.

When Popover opens, focus is sent to the popover content. When it closes, focus is returned to the trigger.

Note

When using this component, ensure the children passed to PopoverTrigger is focusable and has a forwarded ref.

live

<Popover header="Confirmation!" trigger={<Button>Trigger</Button>} inPortal>
  Are you sure you want to have that milkshake?
</Popover>

Close button

Pass isClosable to enable the built-in close button.

live

<Popover
  isClosable
  header="Confirmation!"
  trigger={<Button>Trigger</Button>}
  inPortal
>
  Are you sure you want to have that milkshake?
</Popover>

Action

When there is a single action associated with the popover, render a PopoverButton in the footer.

live

<Popover
  header="With Action"
  trigger={<Button>Trigger</Button>}
  footer={<PopoverButton>Action</PopoverButton>}
  inPortal
>
  Popover with a single action. Lorem ipsum dolor sit amet, consectetur
  adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore.
</Popover>

Hover

Pass isHover to open the popover when the trigger is hovered instead of clicked.

live

<Popover
  isHover
  header="Confirmation!"
  trigger={<Button>Trigger</Button>}
  inPortal
>
  Are you sure you want to have that milkshake?
</Popover>

Color mode

By default, Popover uses the color mode context to determine whether to display a dark or light placeholder animation. Pass colorMode to manually force a color mode.

live

<HStack>
  <Popover
    colorMode="light"
    header="Confirmation!"
    trigger={<Button>Light</Button>}
    footer={<PopoverButton>Yes!</PopoverButton>}
    isClosable
    inPortal
  >
    Are you sure you want to have that milkshake?
  </Popover>
  <Popover
    colorMode="dark"
    header="Confirmation!"
    trigger={<Button>Dark</Button>}
    footer={<PopoverButton>Yes!</PopoverButton>}
    isClosable
    inPortal
  >
    Are you sure you want to have that milkshake?
  </Popover>
</HStack>

Variant

By default, Popover uses a solid background. Use the glass variant when displaying popovers over media, such as images.

live

<HStack>
  <Popover
    colorMode="light"
    variant="glass"
    header="Confirmation!"
    trigger={<Button>Light Glass</Button>}
    footer={<PopoverButton>Yes!</PopoverButton>}
    isClosable
    inPortal
  >
    Are you sure you want to have that milkshake?
  </Popover>
  <Popover
    colorMode="dark"
    variant="glass"
    header="Confirmation!"
    trigger={<Button>Dark Glass</Button>}
    footer={<PopoverButton>Yes!</PopoverButton>}
    isClosable
    inPortal
  >
    Are you sure you want to have that milkshake?
  </Popover>
</HStack>

To render a popover in a Portal, pass the inPortal prop.

Info

These live code blocks hide overflow, so we're setting inPortal on all the examples

live

<Popover
  inPortal
  header="Header"
  footer="This is the footer"
  trigger={<Button>Trigger</Button>}
>
  Are you sure you want to have that milkshake?
</Popover>

Initial focus

By default, focus is to sent to the popover content when it opens. Pass the initialFocusRef prop to send focus to a specific element instead.

Note

Focusing a child element only works for popovers with a click trigger, not when isHover is set.

live

() => {
  const initialFocusRef = React.useRef();
  return (
    <Popover
      initialFocusRef={initialFocusRef}
      placement="bottom"
      trigger={<Button>Trigger</Button>}
      closeOnBlur={false}
      header="Manage Your Channels"
      width="750"
      footer={
        <HStack justifyContent="space-between" mt="300" width="100%">
          <Body size="small" color="neutral.600" fontWeight="bodyBold">
            Step 2 of 4
          </Body>
          <HStack>
            <Button variant="secondary">Setup Email</Button>
            <Button variant="primary" ref={initialFocusRef}>
              Next
            </Button>
          </HStack>
        </HStack>
      }
      inPortal
    >
      Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore.
    </Popover>
  );
};

Controlled usage

You can control the opening and closing of the popover by passing the isOpen, and onClose props.

Sometimes you might need to set the returnFocusOnClose prop to false to prevent popover from returning focus to PopoverTrigger's children.

live

() => {
  const { isOpen, onToggle, onClose } = useDisclosure();
  return (
    <VStack alignItems="stretch" width="fit-content">
      <Button onClick={onToggle}>External Trigger</Button>
      <Popover
        returnFocusOnClose={false}
        isOpen={isOpen}
        onClose={onClose}
        placement="right"
        closeOnBlur={false}
        trigger={<Button variant="secondary">Internal Trigger</Button>}
        header="Confirmation"
        footer={
          <>
            <Button variant="secondary" flex={1} onClick={onClose}>
              Cancel
            </Button>
            <Button colorScheme="danger" flex={1}>
              Apply
            </Button>
          </>
        }
        inPortal
      >
        Are you sure you want to continue with your action?
      </Popover>
    </VStack>
  );
};

Anchor

Pass anchor instead of trigger to prevent trigger any action. The wrapped component will become a position reference.

When passing an anchor instead of a trigger, the state of the Popover must be controlled with external state (controlled mode).

Anchor must accept a ref

As with trigger, if you pass a custom component inside anchor ensure that it uses forwardRef so the popover is triggered successfully.

live

() => {
  const [isEditing, setIsEditing] = useBoolean();
  const [color, setColor] = React.useState('salmon');
  return (
    <HStack>
      <Popover
        isOpen={isEditing}
        onOpen={setIsEditing.on}
        onClose={setIsEditing.off}
        closeOnBlur={false}
        isLazy
        lazyBehavior="keepMounted"
        anchor={
          <TextInput
            color={color}
            w="auto"
            display="inline-flex"
            isDisabled={!isEditing}
            size="small"
            defaultValue="Popover Anchor"
          />
        }
        inPortal
        width="fit-content"
        bodyProps={{ display: 'flex', flexDirection: 'row' }}
      >
        <Label htmlFor="#colors" isSemiBold mr="300">
          Colors:
        </Label>
        <RadioGroup
          value={color}
          onChange={newColor => setColor(newColor)}
          id="colors"
        >
          <HStack>
            <Radio value="salmon">salmon</Radio>
            <Radio value="royalblue">royalblue</Radio>
            <Radio value="turquoise">turquoise</Radio>
            <Radio value="violet">violet</Radio>
          </HStack>
        </RadioGroup>
      </Popover>
      <Button onClick={setIsEditing.toggle}>
        {isEditing ? 'Save' : 'Edit'}
      </Button>
    </HStack>
  );
};

Accessing internal state

All Popover elements have access to the internal popover state (isOpen and onClose). Use the render prop pattern to gain access to them.

live

() => {
  const initialRef = React.useRef();
  return (
    <Popover
      closeOnBlur={false}
      placement="left"
      initialFocusRef={initialRef}
      trigger={({ isOpen }) => (
        <Button iconAfter={isOpen ? iconArrowLeft : iconArrowLeft}>
          Trigger
        </Button>
      )}
      header={({ onClose }) => (
        <>
          This is the <em>header</em>,&nbsp;
          <Link as="button" onClick={onClose}>
            close me
          </Link>.
        </>
      )}
      footer={({ onClose }) => (
        <>
          This is the <em>footer</em>,&nbsp;
          <Link as="button" onClick={onClose}>
            close me
          </Link>.
        </>
      )}
      inPortal
    >
      {({ onClose }) => (
        <Body mt="0" mb="200">
          Hello. Nice to meet you! This is the <em>body</em> of the popover.
          <Link as="button" onClick={onClose} ref={initialRef}>
            Click here to close me.
          </Link>
        </Body>
      )}
    </Popover>
  );
};

Placement

Since popover is powered by Popper, you can change the placement of the popover by passing the placement prop.

The possible values are:

Start	Center	End
`bottom-start`	`bottom` (default)	`bottom-end`
`auto-start`	`auto`	`auto-end`
`top-start`	`top`	`top-end`
`left-start`	`left`	`left-end`
`right-start`	`right`	`right-end`

Info

Even hen you've specified the placement manually, Popover will try to reposition itself in the event that available space at the specified placement isn't enough.

live

() => {
  const [placement, setPlacement] = React.useState('top-start');
  return (
    <HStack>
      <Spacer flex={1} />
      <Popover
        placement={placement}
        header="Popover placement"
        trigger={<Button>Click Me</Button>}
        inPortal
      >
        Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
        tempor incididunt ut labore et dolore.
      </Popover>
      <Select
        flex={1}
        onChange={event => setPlacement(event.target.value)}
        size="small"
        value={placement}
      >
        {[
          'bottom-start',
          'bottom',
          'bottom-end',
          'auto-start',
          'auto',
          'auto-end',
          'top-start',
          'top',
          'top-end',
          'left-start',
          'left',
          'left-end',
          'right-start',
          'right',
          'right-end',
        ].map(p => (
          <option key={p} value={p}>
            {p}
          </option>
        ))}
        ;
      </Select>
    </HStack>
  );
};

By default, the Popover component renders its content to the DOM, meaning that invisible popover contents are still rendered but are hidden by styles.

If you want to defer rendering of popover content until that Popover is opened, you can use the isLazy prop. This is useful if your content needs to be extra performant, or make network calls on mount that should only happen when the component is displayed.

live

<Popover
  isLazy
  inPortal
  header="Lazy Content"
  trigger={<Button>Click Me</Button>}
>
  Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod
  tempor incididunt ut labore et dolore.
</Popover>

Accessibility

Info

When you see the word "trigger", it is referring to the children of PopoverTrigger

Keyboard and Focus

When the popover is opened, focus is moved to the PopoverContent. If the initialFocusRef is set, then focus moves to the element with that ref.
When the popover is closed, focus returns to the trigger. If you set returnFocusOnClose to false, focus will not return.
If trigger is set to hover:
- Focusing on or mousing over the trigger will open the popover.
- Blurring or mousing out of the trigger will close the popover. If you move your mouse into the PopoverContent, it'll remain visible.
If trigger is set to click:
- Clicking the trigger or using the Space or Enter when focus is on the trigger will open the popover.
- Clicking the trigger again will close the popover.
Hitting the Esc key while the popover is open and focus is within the PopoverContent, will close the popover. If you set closeOnEsc to false, it will not close.
Clicking outside or blurring out of the PopoverContent closes the popover. If you set closeOnBlur to false, it will not close.

ARIA Attributes

If the trigger is set to click, the PopoverContent element has role set to dialog. If the trigger is set to hover, the PopoverContent has role set to tooltip.
The PopoverContent has aria-labelledby set to the id of the PopoverHeader.
The PopoverContent has aria-describedby set to the id of the PopoverBody.
The PopoverContent has aria-hidden set to true or false depending on the open/closed state of the popover.
The trigger has aria-haspopup set to true to denote that it triggers a popover.
The trigger has aria-controls set to the id of the PopoverContent to associate the popover and the trigger.
The trigger has aria-expanded set to true or false depending on the open/closed state of the popover.

React Native

Popover is built with Tamagui and provides a non-modal dialog that floats around a trigger for iOS and Android platforms.

Usage

import { iconInfo } from '@hoverinc/icons/native';
import { XStack, YStack } from '@tamagui/stacks';
import React from 'react';
import { Body } from '@hoverinc/design-system-react-native';
import { Heading } from '@hoverinc/design-system-react-native';
import { Icon } from '@hoverinc/design-system-react-native';
import { Popover } from '@hoverinc/design-system-react-native';
const App = () => {
  return (
    <Popover>
      <Popover.Trigger asChild>
        <XStack
          alignItems="center"
          backgroundColor="$backgroundGlass"
          borderRadius="$full"
          gap="$100"
          hitSlop={20}
          padding="$300"
          pressStyle={{ backgroundColor: '$interactiveGlass' }}
        >
          <Icon icon={iconInfo} size="small" />
        </XStack>
      </Popover.Trigger>
      <Popover.Content>
        <YStack gap="$200" paddingBottom="$500">
          <Heading size="xs">Estimates</Heading>
          <Body dimmed size="small">
            Calculate material and labor costs for accurate takeoffs.
          </Body>
        </YStack>
        <Popover.Close asChild>
          <Stack>
            <Heading size="xs">Got it</Heading>
          </Stack>
        </Popover.Close>
      </Popover.Content>
    </Popover>
  );
};

Components

The Popover component exports the following sub-components:

Popover – The main wrapper component that provides context and state management
Popover.Trigger – The trigger element that opens the popover (supports scope prop)
Popover.Content – The container for popover content with custom styling
Popover.Close – The close button component

Placement

The popover can be positioned relative to its trigger using the placement prop:

<Popover placement="bottom">...</Popover>
<Popover placement="top">...</Popover>
<Popover placement="left">...</Popover>
<Popover placement="right">...</Popover>

Controlled vs Uncontrolled

The Popover component supports both controlled and uncontrolled usage:

// Controlled
const [open, setOpen] = useState(false);
<Popover open={open} onOpenChange={setOpen}>...</Popover>
// Uncontrolled
<Popover defaultOpen={false}>...</Popover>

Scoped Popovers

For complex applications with multiple popovers, you can use scoped popovers to isolate popover behavior:

<Popover scope="myScope">
  <Popover.Trigger scope="myScope">
    <XStack alignItems="center" gap="$100">
      <Icon icon={iconInfo} size="small" />
    </XStack>
  </Popover.Trigger>
  <Popover.Content>
    <Text>Scoped Content</Text>
  </Popover.Content>
</Popover>

Custom Offset

You can customize the offset distance from the trigger:

<Popover offset={-50}>...</Popover>

PinInput

Portal

Settings

Popover

React

Basic usage

Note

Close button

Action

Hover

Color mode

Variant

Rendering the Popover in a Portal

Info

Initial focus

Note

Controlled usage

Anchor

Anchor must accept a ref

Accessing internal state

Placement

Info

Lazily mounting Popover

Accessibility

Info

Keyboard and Focus

ARIA Attributes

React Native

Usage

Components

Placement

Controlled vs Uncontrolled

Scoped Popovers

Custom Offset