# Popover

- Page: https://jiguang132.com/resources/material-ui/docs/popover
- Resource: Material UI (https://jiguang132.com/resources/material-ui.md)
- All guides: https://jiguang132.com/resources/material-ui/docs.md

Anchor content in a modal-style popover with origin and close handling.

This guide covers Material UI Core with the default Emotion engine; extensions and additional demos are explicitly classified.

## Use case and business boundary

Popover includes Modal behavior; use Popper when non-modal positioning is intended and manage real anchor lifetimes.

## Native composition and scope

`Grow`, `Popover`

Preserve native Material UI composition and types; do not substitute JGuang UI/Base UI/Radix APIs. Example entries are not extra components.

## Native installation and initialization

```bash
npm install @mui/material@9.4.0 @emotion/react@11.14.0 @emotion/styled@11.14.1
```

Use native npm and Emotion, not an invented JGuang UI Registry URL. Place examples inside native ThemeProvider; choose CssBaseline or ScopedCssBaseline for the project. Inspect React, existing providers, lockfile and SSR first. Never overwrite files or conceal peer conflicts. This batch verified React 19.2.8; React 18 and below require matching react-is. See the included bilingual setup guide.

## Practical native parameters

These selected parameters are not a flattened universal API. Preserve the native declaring owner, slot structure, nullable values and generics.

| Owner.prop | Practical role | Declaration source |
| --- | --- | --- |
| `Popover.open` | Controlled native visibility; it does not fetch data or execute actions. | `Popover` |
| `Popover.anchorEl` | Actual or supported virtual anchor; preserve the owning type and lifetime. | `Popover` |
| `Popover.anchorOrigin` | Native vertical/horizontal origin pair. | `Popover` |
| `Popover.transformOrigin` | Native popover content alignment origin. | `Popover` |
| `Popover.onClose` | Native request to close; reason/event signatures differ and the host updates open. | `Popover` |

## Runnable native examples

Machine keys select example entries, not universal variant props. Native demo JSX/data stay unchanged; JGuang-authored acceptance fixtures are explicitly labelled.

- Basic Popover · `BasicPopover` · upstream native demo
- Mouse hover interaction · `MouseHoverPopover` · upstream native demo
- Virtual element · `VirtualElementPopover` · upstream native demo

## Explicitly unsupported additional examples

These remain in the upstream inventory, not silently skipped or presented as working previews. Additional dependency/framework acceptance is required.

- Anchor playground · `AnchorPlayground`: `@mui/internal-core-docs/HighlightedCode`
- material-ui-popup-state · `PopoverPopupState`: `material-ui-popup-state`

## Actual usage example

Unmodified pinned native demo; copy its required local helper files together.

```tsx
import * as React from 'react';
import Popover from '@mui/material/Popover';
import Typography from '@mui/material/Typography';
import Button from '@mui/material/Button';

export default function BasicPopover() {
  const [anchorEl, setAnchorEl] = React.useState<HTMLButtonElement | null>(null);

  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
    setAnchorEl(event.currentTarget);
  };

  const handleClose = () => {
    setAnchorEl(null);
  };

  const open = Boolean(anchorEl);
  const id = open ? 'simple-popover' : undefined;

  return (
    <div>
      <Button aria-describedby={id} variant="contained" onClick={handleClick}>
        Open Popover
      </Button>
      <Popover
        id={id}
        open={open}
        anchorEl={anchorEl}
        onClose={handleClose}
        anchorOrigin={{
          vertical: 'bottom',
          horizontal: 'left',
        }}
      >
        <Typography sx={{ p: 2 }}>The content of the Popover.</Typography>
      </Popover>
    </div>
  );
}

```

## Example dependency boundaries

`react`, `@mui/material/Popover`, `@mui/material/Typography`, `@mui/material/Button`, `@mui/material/Paper`

Direct Icons/System/Utils example imports require their matching 9.4.0 packages. Relative data/helpers are part of the example closure, not extra components. Remote images and simulated operations do not supply a backend.

## Pinned upstream API metadata reference

These tables retain the upstream metadata, not a newly inferred generic type system. Conditional generics, inherited props and callback details are defined by the source declarations below. Theme defaults may override metadata defaults.

### Grow

```tsx
import Grow from '@mui/material/Grow';
import { Grow } from '@mui/material';
```

Native inheritance: `Transition`. Parent/DOM props are not fabricated as additional own props.

| Prop | Required | Upstream metadata type / constraint | Metadata default |
| --- | --- | --- | --- |
| `children` | yes | `element` | — |
| `addEndListener` | no | `func` | — |
| `appear` | no | `bool` | `true` |
| `disablePrefersReducedMotion` | no | `bool` | `false` |
| `easing` | no | `{ enter?: string, exit?: string } \| string` | — |
| `in` | no | `bool` | — |
| `timeout` | no | `'auto' \| number \| { appear?: number, enter?: number, exit?: number }` | `'auto'` |



### Popover

```tsx
import Popover from '@mui/material/Popover';
import { Popover } from '@mui/material';
```

Native inheritance: `Modal`. Parent/DOM props are not fabricated as additional own props.

| Prop | Required | Upstream metadata type / constraint | Metadata default |
| --- | --- | --- | --- |
| `open` | yes | `bool` | — |
| `action` | no | `ref` | — |
| `anchorEl` | no | `HTML element \| func` | — |
| `anchorOrigin` | no | `{ horizontal: 'center' \| 'left' \| 'right' \| number, vertical: 'bottom' \| 'center' \| 'top' \| number }` | `{ vertical: 'top', horizontal: 'left', }` |
| `anchorPosition` | no | `{ left: number, top: number }` | — |
| `anchorReference` | no | `'anchorEl' \| 'anchorPosition' \| 'none'` | `'anchorEl'` |
| `children` | no | `node` | — |
| `classes` | no | `object` | — |
| `container` | no | `HTML element \| func` | — |
| `disableAutoFocus` | no | `bool` | `false` |
| `disableScrollLock` | no | `bool` | `false` |
| `elevation` | no | `integer` | `8` |
| `marginThreshold` | no | `number` | `16` |
| `onClose` | no | `func` | — |
| `slotProps` | no | `{ backdrop?: func \| object, paper?: func \| object, root?: func \| object, transition?: func \| object }` | `{}` |
| `slots` | no | `{ backdrop?: elementType, paper?: elementType, root?: elementType, transition?: elementType }` | `{}` |
| `sx` | no | `Array<func \| object \| bool> \| func \| object` | — |
| `transformOrigin` | no | `{ horizontal: 'center' \| 'left' \| 'right' \| number, vertical: 'bottom' \| 'center' \| 'top' \| number }` | `{ vertical: 'top', horizontal: 'left', }` |
| `transitionDuration` | no | `'auto' \| number \| { appear?: number, enter?: number, exit?: number }` | `'auto'` |


## Native source declarations

Declarations/imports are extracted from pinned source without flattening unions or external inheritance. Original English comments/types are source reference, not a claim of translated upstream prose. Shared types stay in their native packages.

### vendor/src/Grow/Grow.d.ts

```ts
import * as React from 'react';

import { TransitionProps } from '../transitions/types';

export interface GrowProps extends Omit<TransitionProps, 'timeout'> {
  /**
   * Add a custom transition end trigger.
   * Use it when you need custom logic to decide when the transition has ended.
   * Note: Timeouts are still used as a fallback if provided.
   *
   * @param {HTMLElement} node The transitioning DOM node.
   * @param {Function} done Call this when the transition has finished.
   */
  addEndListener?: TransitionProps['addEndListener'] | undefined;
  /**
   * Perform the enter transition when it first mounts if `in` is also `true`.
   * Set this to `false` to disable this behavior.
   * @default true
   */
  appear?: boolean | undefined;
  /**
   * A single child content element.
   */
  children: React.ReactElement<unknown, any>;
  /**
   * If `true`, the transition ignores `theme.motion.reducedMotion` and keeps its normal timing.
   * @default false
   */
  disablePrefersReducedMotion?: boolean | undefined;
  /**
   * The transition timing function.
   * You may specify a single easing or a object containing enter and exit values.
   */
  easing?: TransitionProps['easing'] | undefined;
  /**
   * If `true`, the component will transition in.
   */
  in?: boolean | undefined;
  ref?: React.Ref<unknown> | undefined;
  /**
   * The duration for the transition, in milliseconds.
   * You may specify a single timeout for all transitions, or individually with an object.
   *
   * Set to 'auto' to automatically calculate transition time based on height.
   * @default 'auto'
   */
  timeout?: TransitionProps['timeout'] | 'auto' | undefined;
}

export default function Grow(props: GrowProps): React.JSX.Element;
```

### vendor/src/Popover/Popover.d.ts

```ts
import * as React from 'react';

import { SxProps } from '@mui/system';

import { SlotComponentProps } from '@mui/utils/types';

import { BackdropProps } from '../Backdrop';

import { Theme } from '../styles';

import { InternalStandardProps as StandardProps } from '../internal';

import { PaperProps } from '../Paper';

import { ModalProps } from '../Modal';

import { TransitionProps } from '../transitions/types';

import { PopoverClasses } from './popoverClasses';

import { CreateSlotsAndSlotProps, SlotProps } from '../utils/types';

export interface PopoverSlots {
  /**
   * The component used for the root slot.
   * @default Modal
   */
  root: React.ElementType;
  /**
   * The component used for the paper slot.
   * @default Paper
   */
  paper: React.ElementType;
  /**
   * The component used for the transition slot.
   * @default Grow
   */
  transition: React.ElementType;
  /**
   * The component used for the backdrop slot.
   * @default Backdrop
   */
  backdrop: React.ElementType;
}

export interface PopoverRootSlotPropsOverrides {}

export interface PopoverPaperSlotPropsOverrides {}

export interface PopoverTransitionSlotPropsOverrides {}

export interface PopoverBackdropSlotPropsOverrides {}

export type PopoverSlotsAndSlotProps = CreateSlotsAndSlotProps<
  PopoverSlots,
  {
    /**
     * Props forwarded to the root slot.
     * By default, the available props are based on the [Modal](https://mui.com/material-ui/api/modal/#props) component.
     */
    root: SlotProps<
      React.ElementType<ModalProps>,
      PopoverRootSlotPropsOverrides,
      PopoverOwnerState
    >;
    /**
     * Props forwarded to the paper slot.
     * By default, the available props are based on the [Paper](https://mui.com/material-ui/api/paper/#props) component.
     */
    paper: SlotProps<
      React.ElementType<PaperProps>,
      PopoverPaperSlotPropsOverrides,
      PopoverOwnerState
    >;
    /**
     * Props forwarded to the transition slot.
     * By default, the available props are based on the [Grow](https://mui.com/material-ui/api/grow/#props) component.
     */
    transition: SlotComponentProps<
      // use SlotComponentProps because transition slot does not support `component` and `sx` prop
      React.ElementType<TransitionProps>,
      TransitionProps & PopoverTransitionSlotPropsOverrides,
      PopoverOwnerState
    >;
    /**
     * Props forwarded to the backdrop slot.
     * By default, the available props are based on the [Backdrop](https://mui.com/material-ui/api/backdrop/#props) component.
     */
    backdrop: SlotProps<
      React.ElementType<BackdropProps>,
      PopoverBackdropSlotPropsOverrides,
      PopoverOwnerState
    >;
  }
>;

export interface PopoverOrigin {
  vertical: 'top' | 'center' | 'bottom' | number;
  horizontal: 'left' | 'center' | 'right' | number;
}

export interface PopoverPosition {
  top: number;
  left: number;
}

export type PopoverReference = 'anchorEl' | 'anchorPosition' | 'none';

interface PopoverVirtualElement {
  getBoundingClientRect: () => DOMRect;
  nodeType: Node['ELEMENT_NODE'];
}

export interface PopoverProps
  extends
    StandardProps<
      Omit<ModalProps, 'slots' | 'slotProps' | 'BackdropProps' | 'BackdropComponent'>,
      'children'
    >,
    PopoverSlotsAndSlotProps {
  /**
   * A ref for imperative actions.
   * It currently only supports updatePosition() action.
   */
  action?: React.Ref<PopoverActions> | undefined;
  /**
   * An HTML element, [PopoverVirtualElement](https://mui.com/material-ui/react-popover/#virtual-element),
   * or a function that returns either.
   * It's used to set the position of the popover.
   */
  anchorEl?:
    | null
    | Element
    | PopoverVirtualElement
    | (() => Element | PopoverVirtualElement | null)
    | undefined;
  /**
   * This is the point on the anchor where the popover's
   * `anchorEl` will attach to. This is not used when the
   * anchorReference is 'anchorPosition'.
   *
   * Options:
   * vertical: [top, center, bottom];
   * horizontal: [left, center, right].
   * @default {
   *   vertical: 'top',
   *   horizontal: 'left',
   * }
   */
  anchorOrigin?: PopoverOrigin | undefined;
  /**
   * This is the position that may be used to set the position of the popover.
   * The coordinates are relative to the application's client area.
   */
  anchorPosition?: PopoverPosition | undefined;
  /**
   * This determines which anchor prop to refer to when setting
   * the position of the popover.
   * @default 'anchorEl'
   */
  anchorReference?: PopoverReference | undefined;
  /**
   * The content of the component.
   */
  children?: React.ReactNode;
  /**
   * Override or extend the styles applied to the component.
   */
  classes?: Partial<PopoverClasses> | undefined;
  /**
   * An HTML element, component instance, or function that returns either.
   * The `container` will passed to the Modal component.
   *
   * By default, it uses the body of the anchorEl's top-level document object,
   * so it's simply `document.body` most of the time.
   */
  container?: ModalProps['container'] | undefined;
  /**
   * The elevation of the popover.
   * @default 8
   */
  elevation?: number | undefined;
  /**
   * Specifies how close to the edge of the window the popover can appear.
   * If null, the popover will not be constrained by the window.
   * @default 16
   */
  marginThreshold?: number | null | undefined;
  onClose?: ModalProps['onClose'] | undefined;
  /**
   * If `true`, the component is shown.
   */
  open: boolean;
  /**
   * The system prop that allows defining system overrides as well as additional CSS styles.
   */
  sx?: SxProps<Theme> | undefined;
  /**
   * This is the point on the popover which
   * will attach to the anchor's origin.
   *
   * Options:
   * vertical: [top, center, bottom, x(px)];
   * horizontal: [left, center, right, x(px)].
   * @default {
   *   vertical: 'top',
   *   horizontal: 'left',
   * }
   */
  transformOrigin?: PopoverOrigin | undefined;
  /**
   * Set to 'auto' to automatically calculate transition time based on height.
   * @default 'auto'
   */
  transitionDuration?: TransitionProps['timeout'] | 'auto' | undefined;
}

export interface PopoverOwnerState extends Omit<PopoverProps, 'slots' | 'slotProps'> {}

export interface PopoverActions {
  updatePosition(): void;
}

export function getOffsetTop(rect: DOMRect, vertical: number | 'center' | 'bottom' | 'top'): number;

export function getOffsetLeft(
  rect: DOMRect,
  horizontal: number | 'center' | 'right' | 'left',
): number;

type PopoverRootProps = NonNullable<PopoverProps['slotProps']>['root'];

type PopoverPaperProps = NonNullable<PopoverProps['slotProps']>['paper'];

export declare const PopoverRoot: React.FC<PopoverRootProps>;

export declare const PopoverPaper: React.FC<PopoverPaperProps>;

export default function Popover(props: PopoverProps): React.JSX.Element;
```

## Post-install acceptance

Run strict types, production build and real interactions. Check keyboard labels/focus, disabled/error/read-only semantics where natively supported, both themes, narrow screens and reduced motion. Verify callbacks against the real host data; do not declare installation complete from copying a prompt. Initialization fixtures also require server HTML and warning-free hydration.

## Source and license

https://github.com/mui/material-ui/tree/809a7717b4c050ba3f69b75300689f07c050a16e

MIT · @mui/material@9.4.0. Vendor originals and license are preserved. Full original upstream prose remains in vendor/docs and is not represented as fully translated.

---

Index of all JGuang resources: https://jiguang132.com/llms.txt