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

# Popover

Data Display`@rockshin/tao-ui`

[Examples](#examples)[API](#api)

Displays a floating card with rich content anchored to a trigger element, opened by click or hover.

## When to use

Use Popover for rich, non-blocking contextual content behind a click or hover. Use Tooltip for short text-only hints and Modal for blocking interactions.

**Recommended**

- Keep the title to one short line; put detail in the content.
- Use the default hover trigger for read-only previews and trigger="click" for interactive content.
- Keep popup content compact; link out for long-form detail.

**Avoid**

- Do not nest essential workflows inside a hover-only popover.
- Do not chain popovers from inside another popover.

## Examples


### Basic usage
```tsx preview
import { Button, Popover } from '@rockshin/tao-ui';

function PopoverExample() {
  return (
    <Popover
      trigger="click"
      title="Deployment"
      content="Production was updated 2 minutes ago."
    >
      <Button variant="secondary">View status</Button>
    </Popover>
  );
}

export default PopoverExample;
```

### Hover, focus, and click
```tsx preview
import { Button, Popover, Stack } from '@rockshin/tao-ui';

function PopoverTriggers() {
  return (
    <Stack direction="horizontal" gap="md">
      <Popover title="Hover" content="Opens on pointer hover.">
        <Button variant="secondary">Hover</Button>
      </Popover>
      <Popover
        trigger="focus"
        title="Focus"
        content="Opens from keyboard focus."
      >
        <Button variant="secondary">Focus</Button>
      </Popover>
      <Popover
        trigger="click"
        title="Click"
        content="Opens and closes on click."
      >
        <Button variant="secondary">Click</Button>
      </Popover>
    </Stack>
  );
}

export default PopoverTriggers;
```

### Placement and arrow
```tsx preview
import { Button, Popover, Stack } from '@rockshin/tao-ui';

function PopoverPlacements() {
  return (
    <Stack direction="horizontal" gap="md">
      <Popover
        placement="topLeft"
        title="Top left"
        content="Aligned to the left edge."
      >
        <Button variant="secondary">Top left</Button>
      </Popover>
      <Popover
        placement="bottom"
        title="Bottom"
        content="Centered below the trigger."
      >
        <Button variant="secondary">Bottom</Button>
      </Popover>
      <Popover
        placement="right"
        arrow={false}
        title="No arrow"
        content="Arrow disabled."
      >
        <Button variant="secondary">Right</Button>
      </Popover>
    </Stack>
  );
}

export default PopoverPlacements;
```

### Controlled popup and internal dismissal
An action inside the popup can update open and dismiss it after completion.
```tsx preview
import { useState } from 'react';
import { Popover, Button } from '@rockshin/tao-ui';
export default function Example() {
  const [open, setOpen] = useState(false);
  return (
    <Popover
      trigger="click"
      title="Quick action"
      open={open}
      onOpenChange={setOpen}
      content={<Button onClick={() => setOpen(false)}>Done</Button>}
    >
      <Button>Open actions</Button>
    </Popover>
  );
}
```

### Focus trigger
Use trigger=focus for keyboard hints and keep essential instructions visible on the page.
```tsx preview
import { Popover, Input } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Popover
      trigger="focus"
      title="Project code"
      content="Use a short, recognizable identifier."
    >
      <Input aria-label="Project code" placeholder="Focus this input" />
    </Popover>
  );
}
```

### Arrow and delay
Hover delays use seconds, and arrow controls the pointer.
```tsx preview
import { Popover, Button } from '@rockshin/tao-ui';
export default function Example() {
  return (
    <Popover
      title="Details"
      content="Additional context appears after a short delay."
      arrow={false}
      mouseEnterDelay={0.4}
      mouseLeaveDelay={0.2}
    >
      <Button>Hover for details</Button>
    </Popover>
  );
}
```

### Form content
A popup can contain input and actions; submit, report the result, and close it.
```tsx preview
import { useState } from 'react';
import { Popover, Input, Button, Stack } from '@rockshin/tao-ui';
export default function Example() {
  const [open, setOpen] = useState(false);
  const [name, setName] = useState('Workspace');
  return (
    <Stack direction="vertical">
      <Popover
        trigger="click"
        open={open}
        onOpenChange={setOpen}
        title="Rename"
        content={
          <form
            onSubmit={(e) => {
              e.preventDefault();
              setName(String(new FormData(e.currentTarget).get('name')));
              setOpen(false);
            }}
          >
            <Stack direction="vertical">
              <Input
                name="name"
                aria-label="New name"
                defaultValue={name}
                required
              />
              <Button type="submit">Save name</Button>
            </Stack>
          </form>
        }
      >
        <Button>Rename project</Button>
      </Popover>
      <output>{name}</output>
    </Stack>
  );
}
```

## API


### [#](#popover)Popover



| Property | Description | Type | Default Value |
| --- | --- | --- | --- |
| title | Header content of the popup. | `PopoverRender` | `-` |
| content | Body content of the popup. | `PopoverRender` | `-` |
| trigger | How the popup opens. Defaults to `'hover'`. | `PopoverTrigger | PopoverTrigger[] | undefined` | `hover` |
| placement | Popup position relative to the trigger. Defaults to `'top'`. | `PopoverPlacement | undefined` | `top` |
| mouseEnterDelay | Hover delay in seconds before opening. Defaults to `0.1`. | `number | undefined` | `0.1` |
| mouseLeaveDelay | Hover delay in seconds before closing. Defaults to `0.1`. | `number | undefined` | `0.1` |
| arrow | Show a pointing arrow on the popup. Defaults to `true`. | `boolean | { pointAtCenter?: boolean | undefined; } | undefined` | `true` |
| destroyOnHidden | Unmount the popup content while closed. Defaults to `false`. | `boolean | undefined` | `-` |
| destroyTooltipOnHide | @deprecated Use `destroyOnHidden` instead. | `boolean | undefined` | `-` |
| className | Merged onto the popup root. | `string | undefined` | `-` |
| style | Additional style | `CSSProperties | undefined` | `-` |
| children | Exactly one trigger element. | `ReactNode` **(Required)** | `-` |

