Popover

The <Popover /> component is used to provide additional information or actions when screen real estate is limited. When triggered, it displays an overlaying content element that is positioned relative to its trigger element.

The most basic implementation requires a trigger and content.

Show codeCopy code

The popover will display when the trigger element is clicked. To define the trigger, pass in an element as a child to the <Popover /> component. It's recommended to use a button element as the trigger, but any element passed as a child will automatically be injected with the type="button" attribute, along with handlers and accessibility props.

<Popover>
  <Button label="Trigger" />
</Popover>

Show codeCopy code

The content prop accepts any component or element. The popover will automatically close when the user clicks anywhere outside of the opened popover, or when pressing ESC on the keyboard.

If you need one or more elements inside your content that triggers the popover to close, you can use the <PopoverClose /> component. Similar to the trigger, the closing triggers must each be wrapped with this component in order to inject the necessary handlers and accessibility props. NOTE: The <PopoverClose /> component is only applicable when the input is uncontrolled.

const PopoverContent = () => (
  <Box>
    <Flex padding="small" justifyContent="space-between" paddingY="medium" alignItems="center">
      <Heading level={4}>Popover example</Heading>
      <PopoverClose>
        <Button label="Close" iconOnly tone="ghost" icon={CloseIcon} size="small" />
      </PopoverClose>
    </Flex>
    <Text>Popover content</Text>
    <PopoverClose>
      <Button label="Close Popover" />
    </PopoverClose>
  </Box>
);

The popover by default will be positioned at the bottom of the trigger and will respond automatically to the viewport, moving it to the top if there is not enough space. The side can be changed by using the side prop and the alignment can be changed by using the align prop.

The side prop is used to define the position of the popover. The supported values are: "top" | "right" | "bottom" | "left"

The align prop is used to define the alignment of the popover. The supported values are: "start" | "center" | "end"

Show codeCopy code

Use the blank prop when you need to remove the basic styling that the popover comes with by default (backgroundColor, borderRadius, padding, boxShadow).

The collisionPadding can be used to define the padding in px between the content and the borders of the document. While EDS recommends using REMs instead of pixels, the library used for positioning calculates in pixels. It can be used as a number applying the padding equally in all sides or defined in an object with the following keys: top, right, bottom, left.

Show codeCopy code

The popover can be set to open by default by using the defaultOpen prop. This prop won't have any effect if the component is controlled by the open prop.

<Popover content={<PopoverContent />} defaultOpen>
  <Button label="Trigger" />
</Popover>

The onOpenChange handler is called when the open state of the popover changes. It returns true when the popover is open and false when it is closed.

Show codeCopy code

By default the popover will be uncontrolled and will handle its own state. But it can be controlled by using the isOpen prop.

It's important to note that if the isOpen prop is passed you must handle the closing of the Popover as well. In the example below you can see this handled by the button's onClick handler.

Show codeCopy code

The onEscapeKeyDown prop is a callback that gets called when the user clicks the ESC key. It's recommended to use this when controlling the open state of the popover with isOpen and isOpenChange, to provide keyboard accessibility.

Show codeCopy code