## Usage

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.

```tsx live
const PopoverContent = () => (
  <Flex justifyContent="space-between" alignItems="center" gap="small">
    <Text>Popover content</Text>
    <PopoverClose>
      <Button label="Close" iconOnly tone="ghost" icon={CloseIcon} size="small" />
    </PopoverClose>
  </Flex>
);

return (
  <Popover content={<PopoverContent />}>
    <Button label="Trigger" />
  </Popover>
);
```

## Trigger

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.

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

```tsx live
const PopoverContent = () => (
  <Flex backgroundColor="neutral" borderRadius="large" boxShadow="large" width="20rem" flexDirection="column">
    <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>
    <Divider />
    <Box padding="medium">
      <Flex
        alignItems="center"
        backgroundColor="neutralSubtle"
        borderRadius="medium"
        flexDirection="column"
        gap="small"
        height="10rem"
        justifyContent="center"
        padding="medium"
      >
        <Text fontWeight="bold">Content</Text>
      </Flex>
    </Box>
    <Divider />
    <Flex padding="medium" justifyContent="end">
      <PopoverClose>
        <Button label="Cancel" />
      </PopoverClose>
    </Flex>
  </Flex>
);

const AvatarPopover = () => (
  <AvatarGroup>
    <Avatar name="Tony Stark" />
    <Avatar name="Bruce Banner" />
    <Avatar name="Natasha Romanoff" />
    <Avatar name="Peter Parker" />
    <Avatar name="Steve Rogers" />
    <Avatar name="Thor Odinson" />
    <Avatar name="Scott Lang" />
    <Avatar name="King T'Challa" />
    <Avatar name="Clint Barton" />
  </AvatarGroup>
);

const TagPopover = () => (
  <Flex backgroundColor="neutral" borderRadius="large" boxShadow="large" width="30rem" flexDirection="column">
    <Flex padding="small" justifyContent="space-between" paddingY="medium" alignItems="center">
      <Text fontWeight="bold">Annual Leave - Grant</Text>
      <Badge label="Approved" tone="positive" />
    </Flex>
    <Divider />
    <Flex gap="small" flexDirection="column" padding="medium">
      <Flex flexDirection="column">
        <Text fontSize="small" lineHeight="tight" color="neutralSubtle">
          Dates
        </Text>
        <Text>Annual Leave - Grant</Text>
      </Flex>
      <Flex flexDirection="column">
        <Text fontSize="small" lineHeight="tight" color="neutralSubtle">
          Requested
        </Text>
        <Text>0.0 day</Text>
      </Flex>
      <Flex flexDirection="column">
        <Text fontSize="small" lineHeight="tight" color="neutralSubtle">
          Available balance
        </Text>
        <Text>2.34 days</Text>
      </Flex>
    </Flex>
  </Flex>
);

return (
  <Flex justifyContent="center" alignItems="center" gap="xxlarge" flexDirection={{ xsmall: 'column', small: 'row' }}>
    <Flex justifyContent="center" alignItems="center">
      <Popover content={<AvatarPopover />}>
        <Box as="button">
          <AvatarGroup cap={3} size="small">
            <Avatar name="Tony Stark" />
            <Avatar name="Bruce Banner" />
            <Avatar name="Natasha Romanoff" />
            <Avatar name="Peter Parker" />
            <Avatar name="Steve Rogers" />
            <Avatar name="Thor Odinson" />
            <Avatar name="Scott Lang" />
            <Avatar name="King T'Challa" />
            <Avatar name="Clint Barton" />
          </AvatarGroup>
        </Box>
      </Popover>
    </Flex>

    <Flex justifyContent="center" alignItems="center">
      <Popover content={<TagPopover />} blank>
        <Box as="button">
          <Tag label="Tag with popover" />
        </Box>
      </Popover>
    </Flex>

    <Popover content={<PopoverContent />} blank>
      <Button label="Trigger" />
    </Popover>
  </Flex>
);
```

## Content

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.

### PopoverClose

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](/#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.

```jsx
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>
);
```

## Positioning

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.

### Side

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

### Align

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

```tsx live
const [side, setSide] = useState<PopoverProps['side']>('top');
const [align, setAlign] = useState<PopoverProps['align']>('start');

const PositionPopover = () => (
  <Flex flexDirection="column" backgroundColor="neutral" borderRadius="large" boxShadow="large">
    <Flex alignItems="center" padding="small" justifyContent="space-between">
      <Heading level={5}>Popover Position</Heading>
      <PopoverClose>
        <Button label="Close" iconOnly tone="ghost" icon={CloseIcon} size="small" />
      </PopoverClose>
    </Flex>
    <Divider />
    <Flex flexDirection="column" padding="medium">
      <RadioGroup
        value={align ?? 'start'}
        onInputChange={(selectedValue) => setAlign(selectedValue as PopoverProps['align'])}
        horizontal
      >
        {['start', 'center', 'end'].map((value) => (
          <Radio key={value} value={value}>
            {value.charAt(0).toUpperCase() + value.slice(1)}
          </Radio>
        ))}
      </RadioGroup>
      <RadioGroup
        value={side ?? 'top'}
        onInputChange={(selectedValue) => setSide(selectedValue as PopoverProps['side'])}
        horizontal
      >
        {['top', 'right', 'left', 'bottom'].map((value) => (
          <Radio key={value} value={value}>
            {value.charAt(0).toUpperCase() + value.slice(1)}
          </Radio>
        ))}
      </RadioGroup>
    </Flex>
    <Divider />
    <Flex justifyContent="end" padding="medium">
      <PopoverClose>
        <Button label="Close" size="small" />
      </PopoverClose>
    </Flex>
  </Flex>
);

return (
  <Flex height="5rem" justifyContent="center" alignItems="center">
    <Popover content={<PositionPopover />} side={side} align={align} blank>
      <Button label={`${side}-${align}`} />
    </Popover>
  </Flex>
);
```

## Blank

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

## collisionPadding

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`.

```tsx live
const PopoverContent = () => (
  <Flex justifyContent="space-between" alignItems="center" gap="small">
    <Text>Popover content</Text>
    <PopoverClose>
      <Button label="Close" iconOnly tone="ghost" icon={CloseIcon} size="small" />
    </PopoverClose>
  </Flex>
);

return (
  <Popover content={<PopoverContent />} collisionPadding={{ top: 16, left: 16 }}>
    <Button label="Trigger" />
  </Popover>
);
```

## defaultOpen

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.

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

## onOpenChange

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.

```tsx live
const [state, setState] = useState(false);

const PopoverContent = () => (
  <Flex justifyContent="space-between" alignItems="center" gap="small">
    <Text>Popover content</Text>
    <PopoverClose>
      <Button label="Close" iconOnly tone="ghost" icon={CloseIcon} size="small" />
    </PopoverClose>
  </Flex>
);

return (
  <Flex alignItems="center" flexDirection="column" gap="large">
    <Text>
      Popover is <Text fontWeight="bold">{state ? 'open' : 'closed'}</Text>
    </Text>
    <Popover content={<PopoverContent />} onOpenChange={(state) => setState(state)}>
      <Button label="Trigger" />
    </Popover>
  </Flex>
);
```

## Controlled

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.

```tsx live
const [isOpen, setIsOpen] = useState(false);

const PopoverContent = () => (
  <Flex justifyContent="space-between" alignItems="center" gap="small">
    <Text>Popover content</Text>
    <Button label="Close" iconOnly tone="ghost" icon={CloseIcon} size="small" onClick={() => setIsOpen(false)} />
  </Flex>
);

return (
  <Box>
    <Button label="Outside trigger" aria-label="Toggle from outside" onClick={() => setIsOpen((prev) => !prev)} />

    <Flex height="10rem" justifyContent="center" alignItems="center" flexDirection="column" gap="medium">
      <Popover isOpen={isOpen} content={<PopoverContent />}>
        <Button label="Popover" aria-label="Toggle outside" onClick={() => setIsOpen((prev) => !prev)} />
      </Popover>
    </Flex>
  </Box>
);
```

### onEscapeKeyDown

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.

```tsx live
const [state, setState] = useState(false);

const PopoverContent = () => <Text>Press esc to close</Text>;

return (
  <Popover
    content={<PopoverContent />}
    onOpenChange={(state) => setState(state)}
    onEscapeKeyDown={() => setState(false)}
  >
    <Button label="Trigger" />
  </Popover>
);
```

### modal

When set to `true`, interaction with outside elements will be disabled and only popover content will be visible to screen readers.

**Auto-detection** (Recommended): The Popover automatically detects if it's inside a Modal and handles this appropriately. In most cases, you can omit this prop entirely.

- Omit the `modal` prop to use auto-detection (recommended)
- Use `modal={true}` to force modal behavior
- Use `modal={false}` to disable modal behavior

```tsx live
const [state, setState] = useState(false);

return (
  <Box>
    <Popover content={<Text>This uses auto-detected modal behavior</Text>} onOpenChange={setState} isOpen={state}>
      <Button label="Trigger" />
    </Popover>
  </Box>
);
```

If you need to override auto-detection:

```tsx live
const [state, setState] = useState(false);

return (
  <Box>
    <Popover modal={false} content={<Text>Non-modal popover</Text>} onOpenChange={setState} isOpen={state}>
      <Button label="Trigger" />
    </Popover>
  </Box>
);
```

A contextual overlay to provide additional information or actions.

Popover

Accessibility

Responsive layouts

Tokens

Foundations

a11y

Accordion

Actions

AddressInput

AppLayout

Avatar

Badge

Blanket

Breadcrumbs

BulkActionBar

Button

Card

Checkbox

Core

DateDropdown

DateInput

Divider

EmptyState

Field

Fieldset

FileInput

Filtering

Flex

Grid

Heading

Icon

Illustration

Link

List

Loading

Modal

Notice

PageHeader

Pagination

PhoneInput

Radio

RailTrack

RichTextEditor

ScrollWrap

SearchInput

SelectDropdown

SelectInput

ShowMore

Table

Tabs

Text

TextAreaInput

TextInput

Toast

Toggle

Tooltip

Utils

Utils - NextJS

Components

Forms

Search

Tables

Patterns

Introduction

Product tone and voice

Capitalisation

Date and time

Inclusive design

Content

Welcome to EDS

Start designing

Start developing

Contributing

Releases

The EDS way

Coding style guide

Guide to Pendo

Setting up the EDS repo

Creating a new component

Automated testing

PR and changeset process

Publishing snapshots

Publishing packages

Monorepo tools

Team resources