Popover · ui.voila.dev

Usage

import { Popover } from "@voila.dev/ui/popover";

<Popover.Root>
	<Popover.Trigger render={<Button variant="outline">Details</Button>} />
	<Popover.Content>
		<Popover.Header>
			<Popover.Title>Landing page redesign</Popover.Title>
			<Popover.Description>Northwind Labs — June 14.</Popover.Description>
		</Popover.Header>
		<p className="text-muted-foreground">A product designer is needed…</p>
	</Popover.Content>
</Popover.Root>

A small panel anchored to its trigger, for content that belongs next to something rather than over everything. It does not block the page, which is what separates it from Dialog. If the content is a menu of actions, use DropdownMenu — it has the roving focus and typeahead a popover full of buttons will not. If it is a definition or a preview that appears on hover, that is HoverCard; if it is one line of help, Tooltip.

Recipes

Placed above, aligned to the start

side, align, sideOffset and alignOffset are surfaced directly; anything else the positioner takes — collisionPadding, sticky, anchor — goes through positionerProps.

Placement is a preference, not a guarantee: the popover flips and shifts to stay on screen, so a top popover near the top of the viewport renders below the trigger instead.

API

Popover.Root

Prop	Type	Default
`actionsRef`	`RefObject<PopoverRootActions \| null>`	—	A ref to imperative actions.
`children`	`PayloadChildRenderFunction<unknown> \| ReactNode`	—	The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger.
`defaultOpen`	`boolean`	—	Whether the popover is initially open. To render a controlled popover, use the `open` prop instead.
`defaultTriggerId`	`string \| null`	—	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.
`handle`	`PopoverHandle<unknown>`	—	A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state.
`modal`	`"trap-focus" \| boolean`	—	Determines if the popover enters a modal state when open. When `modal` is `true`, focus trapping is enabled only if `<Popover.Close>` is rendered inside `<Popover.Popup>`. It can be visually hidden with your own CSS if needed, such as Tailwind's `sr-only` utility. When `modal` is `'trap-focus'`, render `<Popover.Close>` inside `<Popover.Popup>` so touch screen readers can escape the popup.
`onOpenChange`	`((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void)`	—	Event handler called when the popover is opened or closed.
`onOpenChangeComplete`	`((open: boolean) => void)`	—	Event handler called after any animations complete when the popover is opened or closed.
`open`	`boolean`	—	Whether the popover is currently open.
`triggerId`	`string \| null`	—	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).

Plus the DOM props of the element it renders. Source: popover/components/popover-root.tsx.

Popover.Close

Prop	Type	Default
`className`	`string` \| `((state: PopoverCloseState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`nativeButton`	`boolean`	—	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`).
`render`	`ComponentRenderFn<HTMLProps, PopoverCloseState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: PopoverCloseState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: popover/components/popover-close.tsx.

Popover.Content

Prop	Type	Default
`positionerProps`	`Omit<PopoverPositionerProps, "align" \| "alignOffset" \| "children" \| "side" \| "sideOffset">`	—	Escape hatch for the Positioner props not surfaced as dedicated ones — `collisionPadding`, `sticky`, `anchor`, `positionMethod`, `arrowPadding`.
`align`	`Align`	`"center"`	How to align the popup relative to the specified side.
`alignOffset`	`number \| OffsetFunction`	`0`	Additional offset along the alignment axis in pixels. Also accepts a function that returns the offset to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties:
`className`	`string` \| `((state: PopoverPopupState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`finalFocus`	`boolean` \| `RefObject<HTMLElement \| null>` \| `((closeType: InteractionType) => void` \| `boolean` \| `HTMLElement` \| `null)`	—	Determines the element to focus when the popover is closed.
`initialFocus`	`boolean` \| `RefObject<HTMLElement \| null>` \| `((openType: InteractionType) => void` \| `boolean` \| `HTMLElement` \| `null)`	—	Determines the element to focus when the popover is opened. By default, focus moves to the first tabbable element inside the popup, except when the popover is opened by touch — then the popup itself is focused to avoid opening the virtual keyboard.
`render`	`ComponentRenderFn<HTMLProps, PopoverPopupState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`side`	`Side`	`"bottom"`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
`sideOffset`	`number \| OffsetFunction`	`4`	Distance between the anchor and the popup in pixels. Also accepts a function that returns the distance to read the dimensions of the anchor and positioner elements, along with its side and alignment. The function takes a `data` object parameter with the following properties:
`style`	`CSSProperties` \| `((state: PopoverPopupState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: popover/components/popover-content.tsx.

Popover.Description

Prop	Type	Default
`className`	`string` \| `((state: PopoverDescriptionState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`ComponentRenderFn<HTMLProps, PopoverDescriptionState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: PopoverDescriptionState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: popover/components/popover-description.tsx.

Popover.Header

Prop	Type	Default
`render`	`ComponentRenderFn<HTMLProps, {}>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.

Plus every <div> prop. Source: popover/components/popover-header.tsx.

Popover.Title

Prop	Type	Default
`className`	`string` \| `((state: PopoverTitleState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`ComponentRenderFn<HTMLProps, PopoverTitleState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: PopoverTitleState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: popover/components/popover-title.tsx.

Popover.Trigger

Prop	Type	Default
`className`	`string` \| `((state: PopoverTriggerState) => string` \| `undefined)`	—	CSS class applied to the element, or a function that returns a class based on the component's state.
`closeDelay`	`number`	—	How long to wait before closing the popover that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
`delay`	`number`	—	How long to wait before the popover may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
`handle`	`PopoverHandle<unknown>`	—	A handle to associate the trigger with a popover.
`id`	`string`	—	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).
`nativeButton`	`boolean`	—	Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (e.g. `<div>`).
`openOnHover`	`boolean`	—	Whether the popover should also open when the trigger is hovered.
`payload`	`unknown`	—	A payload to pass to the popover when it is opened.
`render`	`ComponentRenderFn<HTMLProps, PopoverTriggerState>` \| `ReactElement<unknown, string \| JSXElementConstructor<any>>`	—	Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties` \| `((state: PopoverTriggerState) => CSSProperties` \| `undefined)`	—	Style applied to the element, or a function that returns a style object based on the component's state.

Plus the DOM props of the element it renders. Source: popover/components/popover-trigger.tsx.

HoverCard · Tooltip · DropdownMenu · Dialog