> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Popover
> Display contextual content anchored to a trigger.
export const StoryEmbed = ({storyId, title, height = 240}) => <>
Open in Storybook
;
Use `Popover` for contextual information or lightweight controls. `Popup` includes positioning and a portal, so you can compose content directly inside it.
## Anatomy
Keep the trigger and popup inside `Popover.Root`. The popup can contain text, form controls, and actions.
```text theme={null}
Popover.Root
├── Popover.Trigger
└── Popover.Popup
├── Popover.Title
├── Popover.Description
└── Popover.Close
```
| Part | Requirement | Purpose |
| ------------- | --------------------------------------- | --------------------------------------------------------------------- |
| `Root` | Required | Coordinates open state and interactions. |
| `Trigger` | Required for a trigger-anchored popover | Opens or closes the popup and supplies its anchor. |
| `Popup` | Required | Renders positioned content with focus management. |
| `Title` | Recommended | Supplies a visible popup name. An accessible name is always required. |
| `Description` | Optional | Associates explanatory text with the popup. |
| `Close` | Optional | Provides an explicit close action within the popup. |
`Popup` includes the portal and positioner. Set `arrow` on `Popup` to add its built-in arrow. All parts share their root's context even though the popup renders in a portal; the tree describes component nesting, not the final DOM placement.
## Uncontrolled state
Use `defaultOpen` to set the initial visibility. The popover owns subsequent changes from its trigger, close controls, and dismissal interactions.
```tsx theme={null}
import { Popover } from 'twenty-ui/primitives/surfaces';
export const ImportHelp = () => (
Import helpImport a CSV file
Use a header row to identify your columns.
Got it
);
```
`defaultOpen` defaults to `false`, so it can be omitted. Use `Title` and `Description` to identify the popup. The trigger renders a button by default; `render` lets you supply a compatible element.
## Controlled state
Pass `open` and update it with `onOpenChange` to own the same popover's visibility in React state.
```tsx theme={null}
import { useState } from 'react';
import { Popover } from 'twenty-ui/primitives/surfaces';
export const ImportHelp = () => {
const [open, setOpen] = useState(false);
return (
Import helpImport a CSV file
Use a header row to identify your columns.
Got it
);
};
```
`onOpenChange` receives the next boolean and event details, including changes requested by the trigger, close controls, Escape, and outside interaction.
## Compose with buttons
Pass a Twenty UI `Button` through `render` to use it as the trigger or close control. The popover keeps its open state, keyboard behavior, and focus handling.
```tsx theme={null}
import { Button } from 'twenty-ui/primitives/input';
import { Popover } from 'twenty-ui/primitives/surfaces';
export const ImportHelp = () => (
}
/>
Import a CSV file
Use a header row to identify your columns.
} />
);
```
`render` composes behavior onto the supplied button. Custom wrapper components must [forward the supplied props and ref](/ui/primitives/overview#custom-components) to preserve that behavior.
## Placement and focus
`Popup` defaults to `side="bottom"`, `align="center"`, and `sideOffset={8}`. Set `arrow` to show an arrow. Set `container` to override the theme's portal container; see [theming](/ui/theming).
Escape closes the popup and focus returns to the trigger. Outside interaction dismisses it by default. Use the focus props on `Popup` when its content needs a specific initial or return focus target.
## Props
The reference is generated from the public component types. Native attributes, including accessible names and event handlers, are also accepted on parts that render elements.
### Popover.Root
A ref to imperative actions.
* `unmount`: Manually unmounts the popover.
Call this after any externally controlled closing animation finishes.
* `close`: Closes the popover imperatively when called.
The content of the popover.
This can be a regular React node or a render function that receives the `payload` of the active trigger.
Whether the popover is initially open.
To render a controlled popover, use the `open` prop instead.
ID of the trigger that the popover is associated with.
This is useful in conjunction with the `defaultOpen` prop to create an initially open popover.
A handle to associate the popover with a trigger.
If specified, allows external triggers to control the popover's open state.
Determines if the popover enters a modal state when open.
* `true`: user interaction is limited to the popover: document page scroll is locked, and pointer interactions on outside elements are disabled.
* `false`: user interaction with the rest of the document is allowed.
* `'trap-focus'`: focus is trapped inside the popover, but document page scroll is not locked and pointer interactions outside of it remain enabled.
On touch devices, a `true` modal blocks outside taps but leaves the page scrollable unless the popup spans nearly the full viewport width, matching native iOS behavior.
When `modal` is `true`, focus trapping is enabled only if `` is rendered
inside ``. It can be visually hidden with your own CSS if needed, such as
Tailwind's `sr-only` utility.
When `modal` is `'trap-focus'`, render `` inside `` so touch
screen readers can escape the popup.
Event handler called when the popover is opened or closed.
Event handler called after any animations complete when the popover is opened or closed.
Whether the popover is currently open.
ID of the trigger that the popover is associated with.
This is useful in conjunction with the `open` prop to create a controlled popover.
There's no need to specify this prop when the popover is uncontrolled (that is, when the `open` prop is not set).
### Popover.Trigger
CSS class applied to the element, or a function that
returns a class based on the component's state.
How long to wait before closing the popover that was opened on hover.
Specified in milliseconds.
Requires the `openOnHover` prop.
How long to wait before the popover may be opened on hover. Specified in milliseconds.
Requires the `openOnHover` prop.
A handle to associate the trigger with a popover.
ID of the trigger. In addition to being forwarded to the rendered element,
it is also used to specify the active trigger for the popover in controlled mode (with the PopoverRoot `triggerId` prop).
Whether the component renders a native `