Popover

Show contextual content in an anchored floating panel.

View component source ↗

Preview

Example

A minimal example to get started.

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/popover.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

import { Button } from "@/components/ui/button";
import {
  Popover,
  PopoverTrigger,
  PopoverContent,
  PopoverTitle,
  PopoverDescription,
} from "@/components/ui/popover";

export default function Example() {
  return (
    <Popover>
      <PopoverTrigger render={<Button variant="outline" />}>Details</PopoverTrigger>
      <PopoverContent>
        <PopoverTitle>Workspace settings</PopoverTitle>
        <PopoverDescription>Only invited members can view this workspace.</PopoverDescription>
      </PopoverContent>
    </Popover>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Popover

Popover properties
Prop	Type	Default	Description
`defaultOpen`	boolean \| undefined boolean \| undefined	`false`	Whether the popover is initially open. To render a controlled popover, use the `open` prop instead.
`open`	boolean \| undefined boolean \| undefined	`—`	Whether the popover is currently open.
`onOpenChange`	((open: boolean, eventDetails: PopoverPrimitive.Root.ChangeEventDetails) => void) \| undefi… ((open: boolean, eventDetails: PopoverPrimitive.Root.ChangeEventDetails) => void) \| undefined	`—`	Event handler called when the popover is opened or closed.
`onOpenChangeComplete`	((open: boolean) => void) \| undefined ((open: boolean) => void) \| undefined	`—`	Event handler called after any animations complete when the popover is opened or closed.
`actionsRef`	React.RefObject<PopoverRootActions \| null> \| undefined React.RefObject<PopoverRootActions \| null> \| undefined	`—`	A ref to imperative actions. - `unmount`: When specified, the popover will not be unmounted when closed. Instead, the `unmount` function must be called to unmount the popover manually. Useful when the popover's animation is controlled by an external library. - `close`: Closes the dialog imperatively when called.
`modal`	boolean \| "trap-focus" \| undefined boolean \| "trap-focus" \| undefined	`false`	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. 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.
`triggerId`	string \| null \| undefined string \| null \| undefined	`—`	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).
`defaultTriggerId`	string \| null \| undefined string \| null \| undefined	`—`	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`	PopoverPrimitive.Handle<unknown> \| undefined PopoverPrimitive.Handle<unknown> \| undefined	`—`	A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state.
`children`	React.ReactNode \| PayloadChildRenderFunction<unknown> React.ReactNode \| PayloadChildRenderFunction<unknown>	`—`	The content of the popover. This can be a regular React node or a render function that receives the `payload` of the active trigger.

PopoverContent

PopoverContent properties
Prop	Type	Default	Description
`initialFocus`	boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boo… boolean \| React.RefObject<HTMLElement \| null> \| ((openType: InteractionType) => void \| boolean \| HTMLElement \| null) \| undefined	`—`	Determines the element to focus when the popover is opened. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (first tabbable element or popup). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
`finalFocus`	boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| bo… boolean \| React.RefObject<HTMLElement \| null> \| ((closeType: InteractionType) => void \| boolean \| HTMLElement \| null) \| undefined	`—`	Determines the element to focus when the popover is closed. - `false`: Do not move focus. - `true`: Move focus based on the default behavior (trigger or previously focused element). - `RefObject`: Move focus to the ref element. - `function`: Called with the interaction type (`mouse`, `touch`, `pen`, or `keyboard`). Return an element to focus, `true` to use the default behavior, or `false`/`undefined` to do nothing.
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLDivElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLDivElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined ((event: BaseUIEvent<React.MouseEvent<HTMLDivElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: PopoverPopupState) => string \| undefined) \| undefined string \| ((state: PopoverPopupState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverPopupState> \| undefined	`—`	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`	React.CSSProperties \| ((state: PopoverPopupState) => React.CSSProperties \| undefined) \| un… React.CSSProperties \| ((state: PopoverPopupState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`align`	Align \| undefined Align \| undefined	`"center"`	How to align the popup relative to the specified side.
`side`	Side \| undefined Side \| undefined	`"bottom"`	Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
`sideOffset`	number \| OffsetFunction \| undefined number \| OffsetFunction \| undefined	`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: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.
`alignOffset`	number \| OffsetFunction \| undefined number \| OffsetFunction \| undefined	`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: - `data.anchor`: the dimensions of the anchor element with properties `width` and `height`. - `data.positioner`: the dimensions of the positioner element with properties `width` and `height`. - `data.side`: which side of the anchor element the positioner is aligned against. - `data.align`: how the positioner is aligned relative to the specified side.

PopoverDescription

PopoverDescription properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLParagraphElement> \| undefined React.Ref<HTMLParagraphElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLParagraphElement, Element>>) => void) \| undefine… ((event: BaseUIEvent<React.FocusEvent<HTMLParagraphElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLParagraphElement, Element>>) => void) \| undefine… ((event: BaseUIEvent<React.FocusEvent<HTMLParagraphElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLParagraphElement, Element>>) => void) \| undefin… ((event: BaseUIEvent<React.ChangeEvent<HTMLParagraphElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLParagraphElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLParagraphElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLParagraphElement, MouseEvent>>) => void) \| undef… ((event: BaseUIEvent<React.MouseEvent<HTMLParagraphElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: PopoverDescriptionState) => string \| undefined) \| undefined string \| ((state: PopoverDescriptionState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverDescriptionState> \| undefined	`—`	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`	React.CSSProperties \| ((state: PopoverDescriptionState) => React.CSSProperties \| undefined… React.CSSProperties \| ((state: PopoverDescriptionState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.

PopoverHeader

PopoverHeader properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.

PopoverTitle

PopoverTitle properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLHeadingElement> \| undefined React.Ref<HTMLHeadingElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLHeadingElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLHeadingElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLHeadingElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLHeadingElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLHeadingElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLHeadingElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLHeadingElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLHeadingElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLHeadingElement, MouseEvent>>) => void) \| undefin… ((event: BaseUIEvent<React.MouseEvent<HTMLHeadingElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`className`	string \| ((state: PopoverTitleState) => string \| undefined) \| undefined string \| ((state: PopoverTitleState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverTitleState> \| undefined	`—`	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`	React.CSSProperties \| ((state: PopoverTitleState) => React.CSSProperties \| undefined) \| un… React.CSSProperties \| ((state: PopoverTitleState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.

PopoverTrigger

PopoverTrigger properties
Prop	Type	Default	Description
`nativeButton`	boolean \| undefined boolean \| undefined	`true`	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>`).
`ref`	React.Ref<HTMLButtonElement> \| undefined React.Ref<HTMLButtonElement> \| undefined	`—`	Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`id`	string \| undefined string \| undefined	`—`	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).
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the control receives focus.
`onBlur`	((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.FocusEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the control loses focus.
`onChange`	((event: BaseUIEvent<React.ChangeEvent<HTMLButtonElement, Element>>) => void) \| undefined ((event: BaseUIEvent<React.ChangeEvent<HTMLButtonElement, Element>>) => void) \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	((event: BaseUIEvent<React.KeyboardEvent<HTMLButtonElement>>) => void) \| undefined ((event: BaseUIEvent<React.KeyboardEvent<HTMLButtonElement>>) => void) \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	((event: BaseUIEvent<React.MouseEvent<HTMLButtonElement, MouseEvent>>) => void) \| undefine… ((event: BaseUIEvent<React.MouseEvent<HTMLButtonElement, MouseEvent>>) => void) \| undefined	`—`	Called when the element is activated.
`disabled`	boolean \| undefined boolean \| undefined	`—`	Prevents user interaction.
`name`	string \| undefined string \| undefined	`—`	Field name used in form data.
`type`	"button" \| "submit" \| "reset" \| undefined "button" \| "submit" \| "reset" \| undefined	`—`	The native input or button behavior.
`value`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	The current value when controlled by the application.
`className`	string \| ((state: PopoverTriggerState) => string \| undefined) \| undefined string \| ((state: PopoverTriggerState) => string \| undefined) \| undefined	`—`	CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, PopoverTriggerState> \| undefined	`—`	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`	React.CSSProperties \| ((state: PopoverTriggerState) => React.CSSProperties \| undefined) \| … React.CSSProperties \| ((state: PopoverTriggerState) => React.CSSProperties \| undefined) \| undefined	`—`	Style applied to the element, or a function that returns a style object based on the component's state.
`handle`	PopoverPrimitive.Handle<unknown> \| undefined PopoverPrimitive.Handle<unknown> \| undefined	`—`	A handle to associate the trigger with a popover.
`payload`	unknown unknown	`—`	A payload to pass to the popover when it is opened.
`openOnHover`	boolean \| undefined boolean \| undefined	`false`	Whether the popover should also open when the trigger is hovered.
`delay`	number \| undefined number \| undefined	`300`	How long to wait before the popover may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
`closeDelay`	number \| undefined number \| undefined	`0`	How long to wait before closing the popover that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.

Usage notes

Give the panel a title or accessible label. Use controlled open state when opening or closing depends on application events.