> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/popover.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Popover

Show details or actions next to an element.


## Basic usage

Click the trigger to open. Escape, an outside click or focus leaving dismisses the panel.


View details

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/popover/basic.tsx"
import { Button, Popover } from '@ifhover/leaf-ui';

export function PopoverBasic() {
  return (
    <Popover title="Project details" content="See project details and recent updates here.">
      <Button variant="outline">View details</Button>
    </Popover>
  );
}
```

Expand code


## Examples

### Hover details

Hover mode is for descriptive content and also supports keyboard focus. Use the default click mode for forms or buttons.


Hover for details

hover.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/popover/hover.tsx"
import { Button, Popover } from '@ifhover/leaf-ui';

export function PopoverHover() {
  return (
    <Popover
      title="Project details"
      content="See project details and recent updates here."
      trigger="hover"
    >
      <Button variant="outline">Hover for details</Button>
    </Popover>
  );
}
```

Expand code

### Controlled editing

Control visibility with `open` and `onOpenChange`. Saving updates the project name; reopening after an unsaved close restores the saved value. Click mode moves focus into the panel by default; saving or pressing Escape returns it to the trigger.


Edit projectProject name: Leaf Garden

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/popover/controlled.tsx"
import { Button, Flex, Form, FormField, Input, Popover, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function PopoverControlled() {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState('Leaf Garden');
  const [draft, setDraft] = useState(name);
  return (
    <Flex direction="column" gap="md" align="start">
      <Popover
        title="Edit project"
        width={280}
        open={open}
        onOpenChange={(next) => {
          if (next) setDraft(name);
          setOpen(next);
        }}
        content={
          <Form
            layout="vertical"
            onSubmit={(event) => {
              event.preventDefault();
              setName(draft.trim());
              setOpen(false);
            }}
          >
            <FormField label="Project name">
              <Input
                name="projectName"
                value={draft}
                onChange={(event) => setDraft(event.currentTarget.value)}
                required
              />
            </FormField>
            <Button type="submit" disabled={!draft.trim()}>
              Save and close
            </Button>
          </Form>
        }
      >
        <Button variant="outline">Edit project</Button>
      </Popover>
      <Text role="status" tone="muted">
        Project name: {name}
      </Text>
    </Flex>
  );
}
```

Expand code

### Panel placement

Set the preferred position with `placement`; it adjusts when space is limited.


TopView details

BottomView details

LeftView details

RightView details

placements.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/popover/placements.tsx"
import { Button, Flex, Grid, Popover, Text } from '@ifhover/leaf-ui';

const placements = [
  { placement: 'top', label: 'Top' },
  { placement: 'bottom', label: 'Bottom' },
  { placement: 'left', label: 'Left' },
  { placement: 'right', label: 'Right' },
] as const;

export function PopoverPlacements() {
  return (
    <Flex direction="column" gap="md">
      {placements.map(({ placement, label }) => (
        <Grid
          key={placement}
          role="group"
          aria-label={label}
          columns={{ xs: 1, sm: 2 }}
          gap="8px"
          align="center"
        >
          <Text tone="muted">{label}</Text>
          <Popover
            placement={placement}
            title="Project details"
            content="See project details and recent updates here."
          >
            <Button variant="outline">View details</Button>
          </Popover>
        </Grid>
      ))}
    </Flex>
  );
}
```

Expand code


## API

### Popover API

Configure popup content, triggers and controlled visibility.

The trigger must forward its ref and events. Provide `aria-label` when there is no `title`. Tab can leave the panel; focus is not trapped. See [PopupOptions](https://ifhover.github.io/leaf-ui/en/api/popup-options.md) for shared popup options.

| Property            | Type                                                                                                                                                                 | Default         | Description                                                                                                   |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------- |
| `title`             | `ReactNode`                                                                                                                                                          | `—`             | Popover title.                                                                                                |
| `content`           | `ReactNode`                                                                                                                                                          | Required        | Popover content; use click mode for interactive content.                                                      |
| `children`          | `ReactElement< HTMLAttributes<HTMLElement> & { ref?: Ref<HTMLElement>; disabled?: boolean } >`                                                                       | Required        | Trigger element, with ref and event support                                                                   |
| `trigger`           | `'click' \| 'hover'`                                                                                                                                                 | `'click'`       | Trigger mode                                                                                                  |
| `placement`         | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | `'top'`         | Popup placement                                                                                               |
| `disabled`          | `boolean`                                                                                                                                                            | `false`         | Disable interaction.                                                                                          |
| `open`              | `boolean`                                                                                                                                                            | —               | Controlled open state.                                                                                        |
| `defaultOpen`       | `boolean`                                                                                                                                                            | `false`         | Initial open state for uncontrolled usage.                                                                    |
| `onOpenChange`      | `(open: boolean) => void`                                                                                                                                            | —               | Open state change                                                                                             |
| `autoFocus`         | `boolean`                                                                                                                                                            | `true`          | In click mode, focus the first focusable element or the panel if none exists; hover mode does not move focus. |
| `aria-label`        | `string`                                                                                                                                                             | —               | Accessible name for a popover without a visible title.                                                        |
| `width`             | `number \| string`                                                                                                                                                   | `'max-content'` | Popover width; numbers are pixels.                                                                            |
| `maxWidth`          | `number \| string`                                                                                                                                                   | `320`           | Maximum popover width; numbers are pixels.                                                                    |
| `enterDelay`        | `number`                                                                                                                                                             | `100`           | Delay in milliseconds before opening on hover.                                                                |
| `leaveDelay`        | `number`                                                                                                                                                             | `100`           | Delay in milliseconds before closing after pointer leave.                                                     |
| `className`         | `string`                                                                                                                                                             | —               | CSS class applied to the popover panel.                                                                       |
| `style`             | `CSSProperties`                                                                                                                                                      | —               | Inline styles applied to the popover panel.                                                                   |
| `popupPlacement`    | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | —               | Placement relative to the trigger.                                                                            |
| `popupClassName`    | `string`                                                                                                                                                             | —               | Custom class for the popup.                                                                                   |
| `popupStyle`        | `CSSProperties`                                                                                                                                                      | —               | Custom popup styles.                                                                                          |
| `popupRender`       | `(content: React.ReactNode) => React.ReactNode`                                                                                                                      | —               | Wrap or extend popup content; retain the supplied content to preserve interaction.                            |
| `getPopupContainer` | `() => Element \| DocumentFragment`                                                                                                                                  | —               | Return a popup container, including a ShadowRoot.                                                             |
