Popover

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.

Figma

React

Bootstrap

Native

React

import { Popover } from '@hover/blueprint';

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 shape="box">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 shape="box">Trigger</Button>}
  inPortal
>
  Are you sure you want to have that milkshake?
</Popover>

Hover

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

live

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

Dark color scheme

live

<Popover
  colorScheme="dark"
  header="Confirmation!"
  trigger={<Button shape="box">Trigger</Button>}
  footer={
    <HStack mt="100">
      <Button color="light">Yes!</Button>
    </HStack>
  }
  inPortal
>
  Are you sure you want to have that milkshake?
</Popover>

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 shape="box">Trigger</Button>}
>
  <Button shape="box">Button</Button>
</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 shape="box">Trigger</Button>}
      closeOnBlur={false}
      header="Manage Your Channels"
      width="750"
      footer={
        <HStack justifyContent="space-between" mt="300">
          <Body size={400} color="neutral.600">
            Step 2 of 4
          </Body>
          <HStack>
            <Button shape="box" size="medium" fill="outline">
              Setup Email
            </Button>
            <Button shape="box" size="medium" 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 shape="box" onClick={onToggle}>
        External Trigger
      </Button>
      <Popover
        returnFocusOnClose={false}
        isOpen={isOpen}
        onClose={onClose}
        placement="right"
        closeOnBlur={false}
        trigger={
          <Button color="warning" shape="box">
            Internal Trigger
          </Button>
        }
        header="Confirmation"
        footer={
          <HStack mt="100">
            <Button fill="outline" shape="box" size="medium" onClick={onClose}>
              Cancel
            </Button>
            <Button color="danger" shape="box" size="medium">
              Apply
            </Button>
          </HStack>
        }
        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} shape="box">
        {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 ? iArrowLeft : iArrowRight} shape="box">
          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 shape="box">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 shape="box">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.

Blueprint

Settings

Popover

React

Basic usage

Note

Close button

Hover

Dark color scheme

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