# Popover

URL: https://ark-ui.com/docs/components/popover
Source: https://raw.githubusercontent.com/chakra-ui/ark/refs/heads/main/website/src/content/pages/components/popover.mdx

An overlay that displays additional information or options when triggered.

---

<ComponentPreview id="Popover" />

## Anatomy

<Anatomy id="popover" />

```tsx
<Popover.Root>
  <Popover.Trigger />
  <Popover.Anchor />
  <Popover.Positioner>
    <Popover.Arrow>
      <Popover.ArrowTip />
    </Popover.Arrow>
    <Popover.Content>
      <Popover.Title />
      <Popover.Description />
      <Popover.CloseTrigger />
    </Popover.Content>
  </Popover.Positioner>
</Popover.Root>
```

## Examples

**Example: basic**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Basic() {
  <Popover.Root>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.Title class={styles.Title}>{'Favorite Frameworks'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Manage and organize your favorite web frameworks.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Controlled

Use the `open` and `onOpenChange` props to control the open state of the popover.

**Example: controlled**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import { track } from 'ripple';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Controlled() {
  let open = track(false);

  <Popover.Root
    {open}
    onOpenChange={(e) => {
      @open = e.open;
    }}
  >
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Team Members'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Invite colleagues to collaborate on this project.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Root Provider

An alternative way to control the popover is to use the `RootProvider` component and the `usePopover` hook. This way you
can access the state and methods from outside the component.

**Example: root-provider**

```ripple
import { Popover, usePopover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component RootProvider() {
  const popover = usePopover(
    {
      positioning: {
        placement: 'bottom-start',
      },
    },
  );

  <div class="stack">
    <div>
      {'Popover is '}
      {@popover.open ? 'open' : 'closed'}
    </div>
    <Popover.RootProvider value={popover}>
      <Popover.Trigger class={button.Root}>{'Toggle Popover'}</Popover.Trigger>
      <Portal>
        <Popover.Positioner class={styles.Positioner}>
          <Popover.Content class={styles.Content}>
            <Popover.Title class={styles.Title}>{'Controlled Externally'}</Popover.Title>
            <Popover.Description class={styles.Description}>
              {'This popover is controlled via the usePopover hook.'}
            </Popover.Description>
          </Popover.Content>
        </Popover.Positioner>
      </Portal>
    </Popover.RootProvider>
  </div>
}

```

### Arrow

Use `Popover.Arrow` and `Popover.ArrowTip` to render an arrow pointing to the trigger.

**Example: arrow**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Arrow() {
  <Popover.Root>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.Arrow class={styles.Arrow}>
            <Popover.ArrowTip class={styles.ArrowTip} />
          </Popover.Arrow>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Notifications'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'You have 3 unread messages in your inbox.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Placement

To change the placement of the popover, set the `positioning` prop.

**Example: positioning**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Positioning() {
  <Popover.Root
    positioning={{
      placement: 'left-start',
      offset: { mainAxis: 12, crossAxis: 12 },
    }}
  >
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Left Placement'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'This popover appears on the left with custom offset values.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Close Behavior

The popover is designed to close on blur and when the <kbd>esc</kbd> key is pressed.

- To prevent it from closing on blur (clicking or focusing outside), pass the `closeOnInteractOutside` prop and set it
  to `false`.
- To prevent it from closing when the <kbd>esc</kbd> key is pressed, pass the `closeOnEsc` prop and set it to `false`.

**Example: close-behavior**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component CloseBehavior() {
  <Popover.Root closeOnEscape closeOnInteractOutside>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Quick Actions'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Press Escape or click outside to close this popover.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Modality

In some cases, you might want the popover to be modal. This means that it'll:

- trap focus within its content
- block scrolling on the body
- disable pointer interactions outside the popover
- hide content behind the popover from screen readers

To make the popover modal, set the `modal` prop to `true`. When `modal={true}`, we set the `portalled` attribute to
`true` as well.

**Example: modal**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Modal() {
  <Popover.Root modal>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Confirm Action'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Focus is trapped inside this modal popover until dismissed.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Anchor

Use `Popover.Anchor` to position the popover relative to a different element than the trigger.

**Example: anchor**

```ripple
import { Popover } from 'ark-ripple/popover';
import button from 'styles/button.module.css';
import field from 'styles/field.module.css';
import styles from 'styles/popover.module.css';

export component Anchor() {
  <Popover.Root>
    <div class="hstack">
      <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
      <Popover.Anchor class={styles.Anchor}>
        <input class={field.Input} placeholder="Type here..." />
      </Popover.Anchor>
    </div>

    <Popover.Positioner class={styles.Positioner}>
      <Popover.Content class={styles.Content}>
        <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
        <Popover.Title class={styles.Title}>{'Title'}</Popover.Title>
        <Popover.Description class={styles.Description}>{'Description'}</Popover.Description>
      </Popover.Content>
    </Popover.Positioner>
  </Popover.Root>
}

```

### Same Width

Use `positioning.sameWidth` to make the popover match the width of its trigger element.

**Example: same-width**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component SameWidth() {
  <Popover.Root positioning={{ sameWidth: true }}>
    <Popover.Trigger class={button.Root} style={{ minWidth: '200px' }}>
      {'Click Me'}
    </Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
          <Popover.Title class={styles.Title}>{'Matched Width'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'This popover matches the width of its trigger element.'}
          </Popover.Description>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

### Dialog Integration

When rendering a popover inside a dialog, you have two options for proper layering:

1. **Keep the Portal with `lazyMount` and `unmountOnExit`** - This ensures the popover is properly unmounted when the
   dialog closes, preventing stale DOM nodes.

2. **Remove the Portal** - Render the popover inline within the dialog content. This works well but may have z-index
   considerations.

**Example: with-dialog**

```ripple
import { Dialog } from 'ark-ripple/dialog';
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import dialog from 'styles/dialog.module.css';
import styles from 'styles/popover.module.css';

export component WithDialog() {
  <Dialog.Root>
    <Dialog.Trigger class={button.Root}>{'Open Dialog'}</Dialog.Trigger>
    <Portal>
      <Dialog.Backdrop class={dialog.Backdrop} />
      <Dialog.Positioner class={dialog.Positioner}>
        <Dialog.Content class={dialog.Content}>
          <Dialog.CloseTrigger class={dialog.CloseTrigger}>{'✕'}</Dialog.CloseTrigger>
          <Dialog.Title class={dialog.Title}>{'Edit Profile'}</Dialog.Title>
          <Dialog.Description class={dialog.Description}>
            {'Update your profile information below.'}
          </Dialog.Description>
          <div class={dialog.Body}>
            <Popover.Root lazyMount unmountOnExit>
              <Popover.Trigger class={button.Root}>{'More Options'}</Popover.Trigger>
              <Portal>
                <Popover.Positioner class={styles.Positioner}>
                  <Popover.Content class={styles.Content}>
                    <Popover.Arrow class={styles.Arrow}>
                      <Popover.ArrowTip class={styles.ArrowTip} />
                    </Popover.Arrow>
                    <Popover.CloseTrigger class={styles.CloseTrigger}>{'✕'}</Popover.CloseTrigger>
                    <Popover.Title class={styles.Title}>{'Additional Settings'}</Popover.Title>
                    <Popover.Description class={styles.Description}>
                      {'This popover renders correctly above the dialog.'}
                    </Popover.Description>
                  </Popover.Content>
                </Popover.Positioner>
              </Portal>
            </Popover.Root>
          </div>
        </Dialog.Content>
      </Dialog.Positioner>
    </Portal>
  </Dialog.Root>
}

```

### Nested

Popovers can be nested within each other. Each nested popover maintains its own open state and positioning.

**Example: nested**

```ripple
import { Popover } from 'ark-ripple/popover';
import { Portal } from 'ark-ripple/portal';
import button from 'styles/button.module.css';
import styles from 'styles/popover.module.css';

export component Nested() {
  <Popover.Root>
    <Popover.Trigger class={button.Root}>{'Click Me'}</Popover.Trigger>
    <Portal>
      <Popover.Positioner class={styles.Positioner}>
        <Popover.Content class={styles.Content}>
          <Popover.Title class={styles.Title}>{'Settings'}</Popover.Title>
          <Popover.Description class={styles.Description}>
            {'Manage your preferences and account settings.'}
          </Popover.Description>
          <Popover.Root lazyMount unmountOnExit positioning={{ placement: 'right' }}>
            <Popover.Trigger class={button.Root}>{'Advanced'}</Popover.Trigger>
            <Portal>
              <Popover.Positioner class={styles.Positioner}>
                <Popover.Content class={styles.Content}>
                  <Popover.Title class={styles.Title}>{'Advanced Settings'}</Popover.Title>
                  <Popover.Description class={styles.Description}>
                    {'Configure advanced options for power users.'}
                  </Popover.Description>
                </Popover.Content>
              </Popover.Positioner>
            </Portal>
          </Popover.Root>
        </Popover.Content>
      </Popover.Positioner>
    </Portal>
  </Popover.Root>
}

```

## Guides

### Available Size

The following css variables are exposed to the `Popover.Positioner` which you can use to style the `Popover.Content`

```css
/* width of the popover trigger */
--reference-width: <pixel-value>;
/* width of the available viewport */
--available-width: <pixel-value>;
/* height of the available viewport */
--available-height: <pixel-value>;
```

For example, if you want to make sure the maximum height doesn't exceed the available height, use the following css:

```css
[data-scope='popover'][data-part='content'] {
  max-height: calc(var(--available-height) - 100px);
}
```

## API Reference

### Props

**Component API Reference**

**Root Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `autoFocus` | `boolean` | No | Whether to automatically set focus on the first focusable
content within the popover when opened. |
| `closeOnEscape` | `boolean` | No | Whether to close the popover when the escape key is pressed. |
| `closeOnInteractOutside` | `boolean` | No | Whether to close the popover when the user clicks outside of the popover. |
| `defaultOpen` | `boolean` | No | The initial open state of the popover when rendered.
Use when you don't need to control the open state of the popover. |
| `id` | `string` | No | The unique identifier of the machine. |
| `ids` | `Partial<{
  anchor: string
  trigger: string
  content: string
  title: string
  description: string
  closeTrigger: string
  positioner: string
  arrow: string
}>` | No | The ids of the elements in the popover. Useful for composition. |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `initialFocusEl` | `() => HTMLElement | null` | No | The element to focus on when the popover is opened. |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `modal` | `boolean` | No | Whether the popover should be modal. When set to `true`:
- interaction with outside elements will be disabled
- only popover content will be visible to screen readers
- scrolling is blocked
- focus is trapped within the popover |
| `onEscapeKeyDown` | `(event: KeyboardEvent) => void` | No | Function called when the escape key is pressed |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `onFocusOutside` | `(event: FocusOutsideEvent) => void` | No | Function called when the focus is moved outside the component |
| `onInteractOutside` | `(event: InteractOutsideEvent) => void` | No | Function called when an interaction happens outside the component |
| `onOpenChange` | `(details: OpenChangeDetails) => void` | No | Function invoked when the popover opens or closes |
| `onPointerDownOutside` | `(event: PointerDownOutsideEvent) => void` | No | Function called when the pointer is pressed down outside the component |
| `onRequestDismiss` | `(event: LayerDismissEvent) => void` | No | Function called when this layer is closed due to a parent layer being closed |
| `open` | `boolean` | No | The controlled open state of the popover |
| `persistentElements` | `(() => Element | null)[]` | No | Returns the persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event |
| `portalled` | `boolean` | No | Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position
of the popover content. |
| `positioning` | `PositioningOptions` | No | The user provided options used to position the popover content |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Anchor Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Arrow CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--arrow-size` | The size of the arrow |
| `--arrow-size-half` | Half the size of the arrow |
| `--arrow-background` | Use this variable to style the arrow background |
| `--arrow-offset` | The offset position of the arrow |


**ArrowTip Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**CloseTrigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Content Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | popover |
| `[data-part]` | content |
| `[data-state]` | "open" | "closed" |
| `[data-nested]` | popover |
| `[data-has-nested]` | popover |
| `[data-expanded]` | Present when expanded |
| `[data-placement]` | The placement of the content |


**Content CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--layer-index` | The index of the dismissable in the layer stack |
| `--nested-layer-count` | The number of nested popovers |


**Description Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Indicator Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | popover |
| `[data-part]` | indicator |
| `[data-state]` | "open" | "closed" |


**Positioner Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Positioner CSS Variables:**

| Variable | Description |
|----------|-------------|
| `--reference-width` | The width of the reference element |
| `--reference-height` | The height of the root |
| `--available-width` | The available width in viewport |
| `--available-height` | The available height in viewport |
| `--x` | The x position for transform |
| `--y` | The y position for transform |
| `--z-index` | The z-index value |
| `--transform-origin` | The transform origin for animations |


**RootProvider Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `value` | `UsePopoverReturn` | Yes |  |
| `immediate` | `boolean` | No | Whether to synchronize the present change immediately or defer it to the next frame |
| `lazyMount` | `boolean` | No | Whether to enable lazy mounting |
| `onExitComplete` | `VoidFunction` | No | Function called when the animation ends in the closed state |
| `present` | `boolean` | No | Whether the node is present (controlled by the user) |
| `skipAnimationOnMount` | `boolean` | No | Whether to allow the initial presence animation. |
| `unmountOnExit` | `boolean` | No | Whether to unmount on exit. |


**Title Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Props:**

| Prop | Type | Required | Description |
|------|------|----------|-------------|
| `asChild` | `boolean` | No | Use the provided child element as the default rendered element, combining their props and behavior. |


**Trigger Data Attributes:**

| Attribute | Value |
|-----------|-------|
| `[data-scope]` | popover |
| `[data-part]` | trigger |
| `[data-placement]` | The placement of the trigger |
| `[data-state]` | "open" | "closed" |


### Context

**API:**

| Property | Type | Description |
|----------|------|-------------|
| `portalled` | `boolean` | Whether the popover is portalled. |
| `open` | `boolean` | Whether the popover is open |
| `setOpen` | `(open: boolean) => void` | Function to open or close the popover |
| `reposition` | `(options?: Partial<PositioningOptions>) => void` | Function to reposition the popover |


## Accessibility

### Keyboard Support

<KeyBindingsTable id="popover" />