> To build a Wix site agentically, or add Wix features like bookings or a store to a site you already have, follow https://www.wix.com/headless/skill.md
> 
> Portal Navigation:
> 
> - Append `.md` to any URL under `https://dev.wix.com/docs/` to get its markdown version.
> - Pages are either content pages (article or reference text) or menu pages (a list of links to child pages).
> - To get a menu page, truncate any URL to a parent path and append `.md` (e.g. `https://dev.wix.com/docs/sdk.md`, `https://dev.wix.com/docs/sdk/core-modules.md`).
> - If a reference page seems to be missing its schema (parameters, return types, or type definitions), append `?schema=true` to its `.md` URL (e.g. `https://dev.wix.com/docs/contexts/contexts/stores/category-info/use-category-info-context.md?schema=true`).
> - Top-level index of all portals: https://dev.wix.com/docs/llms.txt
> - Full concatenated docs: https://dev.wix.com/docs/llms-full.txt

## Resource: Popover Component

## Article: Popover Component

## Article Link: https://dev.wix.com/docs/wix-design-system/components/overlays/popover-component.md

## Article Content:

# Popover

_Components/Overlays_

Interactive docs page: <https://wix-pages.com/design-system-documentation/#/component/popover>

## Overview

```jsx
() => {
  const [shown, setShown] = React.useState(true);

  return (
    <Box
      width="250px"
      overflow="hidden"
      border="solid 1px black"
      padding="50px"
    >
      <Popover showArrow shown={shown} appendTo="window" placement="right">
        <Popover.Element>
          <Button onClick={() => setShown((prev) => !prev)}>
            Click me to toggle
          </Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" direction="vertical" maxWidth="200px">
            <Heading size="small">Popover content:</Heading>
            <Text size="small" skin="standard" weight="thin">
              Can be any react node!
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

Popover is a structural component used for showing and positioning pop-ups and tooltips over a given element. It uses Popper.js as engine.

### Do

- Use it to build custom floating content attached to an element when no dedicated component fits.
- Close it when users click outside it or press Escape, with the onClickOutside and onEscPress props.

### Don't

- Don't use it for short labels or explanations. Use `<Tooltip/>` instead.
- Don't use it for a list of actions. Use `<PopoverMenu/>` instead.
- Don't use it to introduce new features. Use `<FloatingHelper/>` instead.

### Feature examples

#### `appendTo="viewport"`

This is similar to the default placement.

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Box
      width="250px"
      overflow="hidden"
      border="solid 1px black"
      padding="50px"
    >
      <Popover showArrow shown={shown} appendTo="viewport" placement="bottom">
        <Popover.Element>
          <Button onClick={() => setShown((prev) => !prev)}>
            Click me to toggle
          </Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" direction="vertical" maxWidth="200px">
            <Heading size="small">Popover content:</Heading>
            <Text size="small" skin="standard" weight="thin">
              Can be any react node!
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### `appendTo="parent"`

If you inspect the content, you'll see it is attached to a new div next to the target element (the Button).

```jsx
() => {
  const [shown, setShown] = React.useState(true);

  return (
    <Box
      width="250px"
      overflow="hidden"
      border="solid 1px black"
      padding="50px"
    >
      <Popover showArrow shown={shown} appendTo="parent" placement="right">
        <Popover.Element>
          <Button onClick={() => setShown((prev) => !prev)}>
            Click me to toggle
          </Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" direction="vertical" maxWidth="200px">
            <Heading size="small">Popover content:</Heading>
            <Text size="small" skin="standard" weight="thin">
              Can be any react node!
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### `appendTo="scrollParent"`

If you inspect the content, you'll see it is attached to a new div under the list container.

```jsx
() => {
  const [shown, setShown] = React.useState(true);

  const ScrollableContent = ({ children }) => (
    <div
      style={{
        overflow: 'hidden',
        position: 'relative',
        border: '1px solid black',
      }}
    >
      <div style={{ overflow: 'auto', height: 120 }}>
        <div style={{ padding: '25px 25px 150px' }}>{children}</div>
      </div>
    </div>
  );

  return (
    <ScrollableContent>
      <Box
        width="250px"
        overflow="hidden"
        border="solid 1px black"
        padding="50px"
      >
        <Popover
          showArrow
          shown={shown}
          appendTo="scrollParent"
          placement="right"
        >
          <Popover.Element>
            <Button onClick={() => setShown((prev) => !prev)}>
              Click me to toggle
            </Button>
          </Popover.Element>
          <Popover.Content>
            <Box padding="12px 24px" direction="vertical" maxWidth="200px">
              <Heading size="small">Popover content:</Heading>
              <Text size="small" skin="standard" weight="thin">
                Can be any react node!
              </Text>
            </Box>
          </Popover.Content>
        </Popover>
      </Box>
    </ScrollableContent>
  );
};
```

#### Interactive with appendTo="parent"

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Box align="center" verticalAlign="middle">
      <Popover
        showArrow
        animate
        placement="right"
        shown={shown}
        onClickOutside={() => setShown(false)}
        appendTo="parent"
      >
        <Popover.Element>
          <Button onClick={() => setShown((prev) => !prev)}>
            Click me to toggle
          </Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" width={140}>
            <Text size="small" skin="standard" weight="thin">
              Clicking inside the popover will not close it, but clicking
              outside will.
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### Non-Interactive with appendTo="window"

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Box align="center" verticalAlign="middle">
      <Popover
        showArrow
        animate
        placement="right"
        shown={shown}
        onClickOutside={() => setShown(false)}
        appendTo="window"
      >
        <Popover.Element>
          <Button onClick={() => setShown((prev) => !prev)}>
            Click me to toggle
          </Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" width={140}>
            <Text size="small" skin="standard" weight="thin">
              Clicking inside the popover will not close it, but clicking
              outside will.
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### Interactive with `appendTo="parent"`

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Box align="center" verticalAlign="middle">
      <Popover
        showArrow
        animate
        placement="right"
        shown={shown}
        onMouseEnter={() => setShown(true)}
        onMouseLeave={() => setShown(false)}
        appendTo="parent"
      >
        <Popover.Element>
          <Button>Hover me to open</Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" width={100}>
            <Text size="small" skin="standard" weight="thin">
              Now hover me!
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### Non-Interactive with `appendTo="window"`

```jsx
() => {
  const [shown, setShown] = React.useState(false);

  return (
    <Box align="center" verticalAlign="middle">
      <Popover
        showArrow
        animate
        placement="right"
        shown={shown}
        onMouseEnter={() => setShown(true)}
        onMouseLeave={() => setShown(false)}
        appendTo="window"
      >
        <Popover.Element>
          <Button>Hover me to open</Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" width={100}>
            <Text size="small" skin="standard" weight="thin">
              Now hover me!
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### Flip enabled and `placement="right"`

```jsx
() => {
  return (
    <Box
      align="center"
      verticalAlign="middle"
      height={80}
      style={{ overflow: 'auto' }}
    >
      <Popover shown showArrow placement="right" appendTo="scrollParent" flip>
        <Popover.Element>
          <Button>I am a plain Button</Button>
        </Popover.Element>
        <Popover.Content>
          <Box align="center" verticalAlign="middle" width={300} height={40}>
            <Text size="small" skin="standard" weight="thin">
              I am a very long popover's content
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### Flip disabled and `placement="right"`

```jsx
() => {
  return (
    <Box
      align="center"
      verticalAlign="middle"
      height={80}
      style={{ overflow: 'auto' }}
    >
      <Popover
        shown
        showArrow
        placement="right"
        appendTo="scrollParent"
        flip={false}
      >
        <Popover.Element>
          <Button>I am a plain Button</Button>
        </Popover.Element>
        <Popover.Content>
          <Box align="center" verticalAlign="middle" width={300} height={40}>
            <Text size="small" skin="standard" weight="thin">
              I am a very long popover's content
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </Box>
  );
};
```

#### Fixed disabled (default) and `placement="top"`

```jsx
() => {
  const ScrollableContent = ({ children }) => (
    <div
      style={{
        overflow: 'hidden',
        position: 'relative',
        border: '1px solid black',
      }}
    >
      <div
        style={{
          overflow: 'auto',
          height: 120,
          display: 'flex',
          justifyContent: 'center',
        }}
      >
        <div style={{ padding: '70px 25px 100px' }}>{children}</div>
      </div>
    </div>
  );

  return (
    <ScrollableContent>
      <Popover
        shown
        showArrow
        placement="top"
        appendTo="scrollParent"
        fixed={false}
      >
        <Popover.Element>
          <Button>I am a plain Button</Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" width={140}>
            <Text size="small" skin="standard" weight="thin">
              Content
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </ScrollableContent>
  );
};
```

#### Fixed enabled and `placement="top"`

```jsx
() => {
  const ScrollableContent = ({ children }) => (
    <div
      style={{
        overflow: 'hidden',
        position: 'relative',
        border: '1px solid black',
      }}
    >
      <div
        style={{
          overflow: 'auto',
          height: 120,
          display: 'flex',
          justifyContent: 'center',
        }}
      >
        <div style={{ padding: '70px 25px 100px' }}>{children}</div>
      </div>
    </div>
  );

  return (
    <ScrollableContent>
      <Popover shown showArrow placement="top" appendTo="scrollParent" fixed>
        <Popover.Element>
          <Button>I am a plain Button</Button>
        </Popover.Element>
        <Popover.Content>
          <Box padding="12px 24px" width={140}>
            <Text size="small" skin="standard" weight="thin">
              Content
            </Text>
          </Box>
        </Popover.Content>
      </Popover>
    </ScrollableContent>
  );
};
```

## Code

```jsx
import { Popover } from '@wix/design-system';
```

### Props

| Name | Type | Default | Description |
| --- | --- | --- | --- |
| `animate` | `boolean` | — | Whether to animate the popover content when it is shown or hidden. |
| `appendTo` | `null \| Element \| "window" \| "scrollParent" \| "viewport" \| "parent" \| Predicate` | — | Enables calculations in relation to a dom element. |
| `aria-describedby` | `string` | — |  |
| `aria-label` | `string` | — |  |
| `aria-labelledby` | `string` | — |  |
| `autoUpdateOptions` | `{ animationFrame?: boolean \| undefined; }` | — | Options controlling how the popover keeps its position in sync with the trigger element while it is shown. |
| `children` | `ReactNode` | — | Sets the trigger and the content of the popover, as `Popover.Element` and `Popover.Content` elements. |
| `customArrow` | `(placement: Placement, arrowProps: object) => ReactNode` | — | Custom arrow element. |
| `dataHook` | `string` | — | Hook for testing purposes. |
| `disableClickOutsideWhenClosed` | `boolean` | `true` | Breaking change: When true, onClickOutside is called only when popover content is shown. |
| `dynamicWidth` | `boolean` | — | popovers content is set to minimum width of trigger element, but it can expand up to the value of maxWidth. |
| `excludeClass` | `string` | — | Clicking on elements with this excluded class doesn't trigger the onClickOutside callback. |
| `fixed` | `boolean` | — | Whether to enable the fixed behaviour. This behaviour is used to keep the `<Popover/>` at it's original placement even when it's being positioned outside the boundary. |
| `flip` | `boolean` | — | Whether to enable the flip behaviour. This behaviour is used to flip the `<Popover/>`'s placement when it starts to overlap the target element (`<Popover.Element/>`). |
| `flipModifier` | `ModifierFn` | — | Custom modifier function for the flip behavior. Receives Popper.js data object and should return the modified data. Use this to implement custom flip logic (e.g., flipping variations on the same side). |
| `fluid` | `boolean` | — |  |
| `hideDelay` | `number` | — | Hide Delay in ms. |
| `id` | `string` | — | Sets the `id` HTML attribute of the popover content element. |
| `interactive` | `boolean` | `true` | Enables hovering the popover content. |
| `maxWidth` | `string \| number` | — | popover content maxWidth value - `number` value which converts to css with `px` - `string` value that contains `px` |
| `minWidth` | `string \| number` | — | popover content minWidth value - `number` value which converts to css with `px` - `string` value that contains `px` |
| `moveArrowTo` | `number` | — | Moves arrow by amount. |
| `moveBy` | `Partial<{ x: number; y: number; }>` | — | Moves popover relative to the parent. |
| `onClick` | `MouseEventHandler` | — | onClick on the component. |
| `onClickOutside` | `(event: Event) => void` | — | Provides callback to invoke when clicked outside of the popover. |
| `onEscPress` | `KeyboardEventHandler<HTMLDivElement>` | — | Provides callback to invoke when popover loses focus. |
| `onHide` | `() => void` | — | Callback to invoke when popover is hidden. |
| `onKeyDown` | `KeyboardEventHandler<HTMLDivElement>` | — | onKeyDown on the target component. |
| `onMouseEnter` | `MouseEventHandler` | — | onMouseEnter on the component. |
| `onMouseLeave` | `MouseEventHandler` | — | onMouseLeave on the component. |
| `onShow` | `() => void` | — | Callback to invoke when popover is shown. |
| `onTabOut` | `(event: KeyboardEvent) => void` | — | Provides callback to invoke when popover loses focus. |
| `overlay` | `ReactNode` | — | Enables overlay for content. |
| `placement` | `"right" \| "left" \| "top" \| "bottom" \| "auto" \| "auto-start" \| "auto-end" \| "top-start" \| "top-end" \| "right-start" \| "right-end" \| "bottom-end" \| "bottom-start" \| "left-end" \| "left-start"` | — | The location to display the content. |
| `ref` | `null \| string \| (instance: PopoverComponent \| null) => void \| RefObject<PopoverComponent>` | — | Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref). |
| `role` | `string` | — | Sets the `role` HTML attribute of the popover content element. |
| `showArrow` | `boolean` | — | Show show arrow from the content. |
| `showDelay` | `number` | — | Show Delay in ms. |
| `shown` | `boolean` | — | Is the content shown or not. |
| `skin` | `"light" \| "dark"` | — | Components skin value. Can be dark or light. |
| `style` | `object` | — | Applies inline styles to the root element of the component. |
| `tabIndex` | `number` | — | tabindex for popover content element. |
| `theme` | `"light" \| "dark"` | — | Controls the color scheme of the popover content. |
| `timeout` | `number \| { enter: number; exit: number; }` | — | Sets the duration of the show and hide animations in milliseconds. Accepts a single number or an object with separate `enter` and `exit` values. |
| `width` | `string \| number` | — | popover content width value - `number` value which converts to css with `px` - `string` value that contains `px` |
| `zIndex` | `string & {} \| "-moz-initial" \| "inherit" \| "initial" \| "revert" \| "revert-layer" \| "unset" \| "auto" \| number & {}` | — | Sets the `z-index` CSS property of the popover content. |

## Testkit

Import the driver matching your test environment:

```jsx
// UniDriver
import { PopoverUniDriver } from '@wix/design-system/dist/testkit/unidriver';

// Vanilla
import { PopoverTestkit } from '@wix/design-system/dist/testkit';

// Puppeteer
import { PopoverTestkit } from '@wix/design-system/dist/testkit/puppeteer';

// Testing Library
import { PopoverTestkit } from '@wix/design-system/dist/testkit/testing-library';
```

### Driver methods

| Method | Description |
| --- | --- |
| `click` | Clicks on the target element |
| `getTargetElement` | Gets the target element |
| `isTargetElementExists` | Checks whether target element exists |
| `getPortalElement` | Gets the portal element |
| `getContentElement` | Gets the content element |
| `isContentElementExists` | Checks whether content element exists |
| `mouseEnter` | Triggers a mouseEnter event |
| `mouseLeave` | Triggers a mouseLeave event |
| `clickOutside` | Clicks outside the target element (triggers mouseDown and mouseUp events) |
| `getArrowOffset` | Gets the arrow offset |
| `getContentElementUniDriver` | Gets content as unidriver element |
| `exists` | Checks whether the component found with the given data hook. |
| `element` | Gets the component root element. |
| `base` | Returns UniDriver for the base element. |

## Changelog

- **1.344.0** (2026-10-28) — maintenance release, no component-specific changes
- **1.340.0** (2026-10-21) — maintenance release, no component-specific changes
- **1.339.0** (2026-10-19) — maintenance release, no component-specific changes
- **1.338.0** (2026-10-15) — maintenance release, no component-specific changes
- **1.332.0** (2026-10-05) — maintenance release, no component-specific changes
- **1.331.0** (2026-10-01) — maintenance release, no component-specific changes
- **1.330.3** (2026-09-29) — maintenance release, no component-specific changes
- **1.330.0** (2026-09-28) — maintenance release, no component-specific changes
- **1.328.0** (2026-09-22) — maintenance release, no component-specific changes
- **1.327.0** (2026-09-21) — feat: supported by `WixDesignSystemDefaultPropsProvider` — a `Popover` key in `defaults` now applies to every instance in the subtree, with instance props still winning. ([#17120](invalid-url))
- **1.325.0** (2026-09-17) — maintenance release, no component-specific changes
- **1.324.0** (2026-09-14) — maintenance release, no component-specific changes
- **1.320.1** (2026-09-04) — maintenance release, no component-specific changes
- **1.317.0** (2026-08-26) — fix: render semantic `wds-popover*` classnames on the root, trigger element, portal, content, and arrow alongside the existing Stylable classes, including the transition status (`--status-open`/`--status-close`) and resolved placement on the content wrapper. ([#16899](invalid-url))
- **1.310.0** (2026-08-10) — maintenance release, no component-specific changes
- **1.303.0** (2026-07-23) — maintenance release, no component-specific changes
- **1.292.0** (2026-06-22) — maintenance release, no component-specific changes
- **1.291.0** (2026-06-19) — maintenance release, no component-specific changes
- **1.279.0** (2026-05-13) — feat: add autoUpdateOptions.animationFrame prop ([#16261](invalid-url))
- **1.278.0** (2026-05-08) — maintenance release, no component-specific changes
- **1.272.0** (2026-04-27) — maintenance release, no component-specific changes
- **1.267.0** (2026-04-09) — maintenance release, no component-specific changes
- **1.266.0** (2026-04-07) — maintenance release, no component-specific changes
- **1.260.0** (2026-03-17) — maintenance release, no component-specific changes
- **1.256.1** (2026-02-10) — fix: clickoutside not working when old popover used with a new one ([#15914](invalid-url))
- **1.248.0** (2026-01-23) — feat: add flipModifier prop for custom flip logic ([#15834](invalid-url))
- **1.247.2** (2026-01-21) — maintenance release, no component-specific changes
- **1.247.0** (2026-01-13) — maintenance release, no component-specific changes
- **1.241.0** (2025-12-17) — maintenance release, no component-specific changes
- **1.220.3** (2025-10-13) — fix: resolve bug in older floating-ui versions ([#15400](invalid-url))
- **1.220.0** (2025-09-29) — maintenance release, no component-specific changes
- **1.213.0** (2025-08-19) — fix: react16 support ([#15212](invalid-url))
- **1.204.0** (2025-07-03) — maintenance release, no component-specific changes
- **1.199.0** (2025-06-13) — maintenance release, no component-specific changes
- **1.196.0** (2025-06-04) — feat: deprecate theme prop ([#14942](invalid-url))
- **1.165.0** (2025-02-27) — maintenance release, no component-specific changes
- **1.156.0** (2025-01-29) — feat: reactive appendTo & appendTo prop type extension ([#14484](invalid-url))
- **1.155.0** (2025-01-23) — maintenance release, no component-specific changes
- **1.145.0** (2024-12-09) — fix: trigger onClickOutside when popover is closed and disableClickOutsideWhenClosed is false ([#14344](invalid-url))
- **1.144.0** (2024-12-03) — maintenance release, no component-specific changes
- **1.143.1** (2024-11-27) — maintenance release, no component-specific changes
- **1.143.0** (2024-11-25) — maintenance release, no component-specific changes
- **1.141.0** (2024-11-19) — maintenance release, no component-specific changes
- **1.139.0** (2024-11-07) — maintenance release, no component-specific changes
- **1.138.1** (2024-10-30) — maintenance release, no component-specific changes
- **1.137.0** (2024-10-25) — maintenance release, no component-specific changes
- **1.116.0** (2024-07-22) — maintenance release, no component-specific changes
- **1.114.0** (2024-07-11) — maintenance release, no component-specific changes
- **1.109.2** (2024-06-17) — maintenance release, no component-specific changes
- **1.109.1** (2024-06-11) — maintenance release, no component-specific changes
- **1.108.0** (2024-06-03) — maintenance release, no component-specific changes
- **1.92.1** (2024-02-05) — maintenance release, no component-specific changes