## Overview [#overview]
`Popover` renders interactive floating content anchored to a trigger. Use it for focused controls, lightweight configuration, or short contextual workflows that need deliberate user interaction.
Popover content is surface-aware: it lands at `parent +2` and uses the matching floating border and shadow for that surface level.
## Usage [#usage]
```tsx
import { Button } from "@tilt-legal/cubitt-components/button";
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@tilt-legal/cubitt-components/popover";
```
```tsx
}>
Show Popover
Premium Plan
Advanced analytics provides deeper insights into your data.
```
## Examples [#examples]
### Basic [#basic]
Click the trigger to open a popover with title, description, and dismiss control.
```tsx
import { Badge } from "@tilt-legal/cubitt-components/badge";
import { Button } from "@tilt-legal/cubitt-components/button";
import {
Popover,
PopoverClose,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@tilt-legal/cubitt-components/popover";
}>
Show Popover
Premium Plan
Advanced analytics provides deeper insights into your data.
Note
Plan upgrade is required.
;
```
### Positions [#positions]
Popover content can be positioned on any side of the trigger.
```tsx
import { Button } from "@tilt-legal/cubitt-components/button";
import {
Popover,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@tilt-legal/cubitt-components/popover";
import { ArrowLeft } from "@tilt-legal/cubitt-icons/ui/outline";
}>
Left
Left Position
This popover appears on the left side of the trigger.
;
```
### Alignment [#alignment]
Popover content can align to the start, center, or end of the trigger.
```tsx
import { Button } from "@tilt-legal/cubitt-components/button";
import {
Popover,
PopoverContent,
PopoverDescription,
PopoverTitle,
PopoverTrigger,
} from "@tilt-legal/cubitt-components/popover";
}>
Align Start
Start Alignment
This popover is aligned to the start of the trigger.
;
```
## API Reference [#api-reference]
### Popover [#popover]
| Prop | Type | Default | Description |
| -------------- | --------------------------------------- | ------- | --------------------------------------------------- |
| `open` | `boolean` | – | Controlled open state. |
| `defaultOpen` | `boolean` | `false` | Initial open state for uncontrolled usage. |
| `onOpenChange` | `(open: boolean, eventDetails) => void` | – | Callback fired when the open state changes. |
| `modal` | `boolean` | `false` | Whether interaction outside the popover is blocked. |
| `disabled` | `boolean` | `false` | Whether the popover is disabled. |
### PopoverTrigger [#popovertrigger]
| Prop | Type | Default | Description |
| ----------- | ----------------------------------------- | ------- | -------------------------------------- |
| `render` | `ReactElement \| (props) => ReactElement` | – | Compose the trigger with another part. |
| `className` | `string` | – | Additional classes for the trigger. |
| `disabled` | `boolean` | `false` | Whether the trigger is disabled. |
### PopoverContent [#popovercontent]
| Prop | Type | Default | Description |
| ---------------- | ---------------------------------------- | ---------- | ------------------------------------------- |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment relative to the trigger. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Side of the trigger to position against. |
| `sideOffset` | `number` | `8` | Distance from the trigger. |
| `alignOffset` | `number` | `0` | Offset along the alignment axis. |
| `anchor` | `RefObject \| Element \| VirtualElement` | – | Optional custom positioning anchor. |
| `positionMethod` | `"absolute" \| "fixed"` | – | Positioning strategy passed to Base UI. |
| `className` | `string` | – | Additional classes for the content surface. |
| `children` | `ReactNode` | – | Popover content. |
### PopoverClose [#popoverclose]
| Prop | Type | Default | Description |
| ----------- | ----------------------------------------- | ------- | ----------------------------------------------------- |
| `render` | `ReactElement \| (props) => ReactElement` | – | Compose the close control with another component. |
| `className` | `string` | – | Additional classes for the close control. |
| `children` | `ReactNode` | – | Close content. Defaults to an icon-only frost button. |
### PopoverTitle [#popovertitle]
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | --------------------------------- |
| `className` | `string` | – | Additional classes for the title. |
| `children` | `ReactNode` | – | Title content. |
### PopoverDescription [#popoverdescription]
| Prop | Type | Default | Description |
| ----------- | ----------- | ------- | --------------------------------------- |
| `className` | `string` | – | Additional classes for the description. |
| `children` | `ReactNode` | – | Description content. |
### PopoverAnchor [#popoveranchor]
| Prop | Type | Default | Description |
| ----------- | -------- | ------- | --------------------------------------- |
| `className` | `string` | – | Additional classes for the anchor span. |