# Popover

```tsx
import { Popover, usePopover } from '@tangible/ui';
```

Interactive docs and examples: [Popover in Storybook](https://storybook-tangible-ui.pages.dev/?path=/docs/overlays-popover--docs).

## Popover props

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `ReactNode` | | |
| `defaultOpen?` | `boolean` | `false` | Default open state for uncontrolled usage. |
| `onOpenChange?` | `(open: boolean) => void` | | Callback when open state changes. |
| `open?` | `boolean` | | Controlled open state. |

### Popover.Trigger

Also exported as `PopoverTrigger`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `ReactNode` | | |
| `asChild?` | `boolean` | `false` | Merge trigger behavior into the child element instead of wrapping it. The child must accept ref and event props (e.g. Button, IconButton). |

### Popover.Content

Also exported as `PopoverContent`.

| Prop | Type | Default | Description |
| - | - | - | - |
| `children` | `ReactNode` | | |
| `align?` | `"center" \| "end" \| "start"` | `'start'` | Alignment along the side. |
| `aria-label?` | `string` | | Accessible name for the dialog. Provide this (or aria-labelledby via a heading inside) so the popover announces meaningfully. |
| `className?` | `string` | | |
| `initialFocus?` | `number` | `0` | Initial focus target: 0 focuses the first tabbable element inside the popover, -1 leaves focus on the trigger. |
| `modal?` | `boolean` | `false` | Trap focus inside the popover while open. Use for content with multiple interactive controls (forms, pickers); leave off for light informational content. |
| `side?` | `"bottom" \| "left" \| "right" \| "top"` | `'bottom'` | Side of the trigger to render against. |
| `sideOffset?` | `number` | `4` | Gap between trigger and content, in px. |
| `style?` | `CSSProperties` | | |

## Hooks

### usePopover

```ts
usePopover(): PopoverContextValue
```

Returns:

| Member | Type | Description |
| - | - | - |
| `open` | `boolean` | |
| `setOpen` | `(open: boolean) => void` | |
| `triggerRef` | `RefObject<HTMLElement \| null>` | |
| `contentId` | `string` | |

## Examples

Stories: Basic, Placement, Form Content, Controlled ([interactive page](https://storybook-tangible-ui.pages.dev/?path=/docs/overlays-popover--docs)).

## Component API tokens

Read via fallback, never declared. Set one on an ancestor to restyle every instance under it.

- `--tui-popover-bg`
- `--tui-popover-fg`
- `--tui-popover-radius`
- `--tui-popover-shadow`
- `--tui-popover-border`
- `--tui-popover-z`
- `--tui-popover-min-width`
- `--tui-popover-max-width`
- `--tui-popover-padding`

---

Interactive version: https://storybook-tangible-ui.pages.dev/?path=/docs/overlays-popover--docs