Popover

The Popover component displays content on top of other content.

<Box position="relative">
  <Popover open={true}>
    <Placeholder size={400} />
  </Popover>
</Box>

Features

The Popover component is a versatile component that can be used in a variety of ways.

Anchoring

The Popover can be anchored to its parent in different ways.

<Box position="relative">
  <Popover
    open={true}
    anchor={{
      strategy: "absolute", // default
      parent: Origin.right,
      child: Origin.bottomRight,
      offset: { x: "-16px", y: "8px" },
    }}
  >
    <Placeholder size={400} />
  </Popover>
</Box>

Open State

You can control the open state of the Popover with the open and onClose props.

() => {
  const [isOpen, setIsOpen] = React.useState(false);
  return (
    <Box position="relative">
      <Button onClick={() => setIsOpen(!isOpen)}>
        {isOpen ? "Close" : "Open"}
      </Button>
      <Popover open={isOpen} onClose={() => setIsOpen(false)}>
        <Placeholder size={400} />
      </Popover>
    </Box>
  );
}

Custom Motion

You can customize the animation of the Popover with the motion and transition props.

() => {
  const [isOpen, setIsOpen] = React.useState(false);
  return (
    <Box position="relative">
      <Button onClick={() => setIsOpen(!isOpen)}>
        {isOpen ? "Close" : "Open"}
      </Button>
      <Popover
        open={isOpen}
        onClose={() => setIsOpen(false)}
        motion={{
          initial: { opacity: 0, y: -8, scale: 0.95 },
          animate: { opacity: 1, y: 0, scale: 1 },
          exit: { opacity: 0, y: -8, scale: 0.95, pointerEvents: "none" },
        }}
        transition={{ duration: 0.15 }}
      >
        <Placeholder size={400} />
      </Popover>
    </Box>
  );
}

Use Cases

The Popover can be used to create a tooltip that appears on hover.

Note

Please note that a Tooltip component is available for this use case.

() => {
      const [isOpen, setIsOpen] = React.useState(false);
      return (
          <Box position="relative" size="fitContent">
              <Button
                  onMouseEnter={() => setIsOpen(true)}
                  onMouseLeave={() => setIsOpen(false)}
              >
                  American Tree Sparrow
              </Button>
              <Popover
                  open={isOpen}
                  anchor={{
                      parent: Origin.top,
                      child: Origin.bottom,
                      offset: { y: "-0.5rem" },
                  }}
              >
                  <Surface padding={400}>
                      Audubon's Oriole
                  </Surface>
              </Popover>
          </Box>
      );
  }

The Popover can be used to create a menu that appears on click.

Note

Please note that a PopoverMenu component is available for this use case.

() => {
    const [isOpen, setIsOpen] = React.useState(false);

    return (
        <Row position="relative" justify="end">
            <IconButton
                variant="tertiary"
                icon={Icon.MoreVert}
                onClick={() => setIsOpen(true)}
            />
            <Popover
                open={isOpen}
                onClose={() => setIsOpen(false)}
                anchor={{
                    parent: Origin.topRight,
                    child: Origin.bottomRight,
                    offset: { y: "-0.5rem" },
                }}
                 motion={{
                    initial: { opacity: 0, y: 8, scaleY: 0.95 },
                    animate: { opacity: 1, y: 0, scaleY: 1 },
                    exit: { opacity: 0, y: 8, scaleY: 0.95, pointerEvents: "none" },
                }}
                transition={{ duration: 0.15 }}
            >
                <Menu items={[
                  { label: "Flesh-footed Shearwater", onClick: () => setIsOpen(false) },
                  { label: "Gray-headed Chickadee", onClick: () => setIsOpen(false) },
                ]} />
            </Popover>
        </Row>
    );

}

Toast

The Popover can be used to create a toast notification.

() => {
  const [isOpen, setIsOpen] = React.useState(false);
  return (
    <>
      <Button onClick={() => setIsOpen(!isOpen)}>
        {isOpen ? "Close" : "Show Toast"}
      </Button>
      <Popover
        open={isOpen}
        anchor={{
          strategy: "fixed",
          parent: Origin.bottom,
          child: Origin.bottom,
          offset: { y: "-1rem" },
        }}
        motion={{
          initial: { opacity: 0, y: "100%" },
          animate: { opacity: 1, y: 0 },
          exit: { opacity: 0, pointerEvents: "none" },
        }}
      >
        <Surface variant="medium" padding={400} onClick={() => setIsOpen(false)}>
          Amoveo uberrime a defero tonsor accommodo.
        </Surface>
      </Popover>
    </>
  );
}

Limitations

Stacking Context

Warning

The Popover does not render in the browser’s top layer. It remains within the stacking context of its parent, which means it can be clipped by ancestors with overflow or clip-path, or be overlapped by elements with a higher z-index.

This is a deliberate trade-off for performance. Rendering in the top layer would disable CSS-based positioning, requiring costly JavaScript calculations to keep the popover anchored. We plan to adopt the CSS anchor() specification for top-layer positioning once browser support is sufficient.

Reference

Props

The Popover component inherits all of the props from the AnimatedBox component and adds the following props.

Name	Type	Default	Description
`open`	`boolean`	`false`	Whether the popover is open.
`onClose`	`() => void`	-	Callback fired when the popover is requested to be closed.
`anchor`	`object`	-	The anchor configuration for the popover.

Anchor Props

The anchor prop takes an object with the following properties:

Name	Type	Default	Description
`parent`	`Origin`	`Origin.center`	The origin point on the parent to anchor to.
`child`	`Origin`	`Origin.center`	The origin point on the popover to anchor from.
`offset`	`object`	-	An object with `x` and `y` properties to offset the popover.
`strategy`	`'absolute' \| 'fixed'`	`'absolute'`	The positioning strategy to use.