Popover

Popover displays floating content anchored to a trigger. Use for inline editing, filter panels, or any secondary UI that needs more space than a Tooltip but should not block the full page like a Dialog.

Code

<Popover>
  <PopoverTrigger render={<Button variant="outline">Open popover</Button>} />

  <PopoverContent>
    <PopoverHeader>
      <PopoverTitle>Order filters</PopoverTitle>
      <PopoverDescription>
        Refine the orders shown in the table.
      </PopoverDescription>
    </PopoverHeader>

    <div className="tw:grid tw:gap-2">
      <div className="tw:grid tw:grid-cols-3 tw:items-center tw:gap-4">
        <Label htmlFor="status">Status</Label>

        <Input
          id="status"
          defaultValue="Confirmed"
          className="tw:col-span-2 tw:h-8"
        />
      </div>
    </div>
  </PopoverContent>
</Popover>

API

Popover

Name	Type/Description
actionsRef	RefObject<PopoverRootActions | null> | undefined 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.
children	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.
defaultOpen = false	boolean | undefined Whether the popover is initially open. To render a controlled popover, use the `open` prop instead.
defaultTriggerId	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	PopoverHandle<unknown> | undefined A handle to associate the popover with a trigger. If specified, allows external triggers to control the popover's open state.
modal = false	boolean | "trap-focus" | undefined 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.
onOpenChange	((open: boolean, eventDetails: PopoverRootChangeEventDetails) => void) | undefined Event handler called when the popover is opened or closed.
onOpenChangeComplete	((open: boolean) => void) | undefined Event handler called after any animations complete when the popover is opened or closed.
open	boolean | undefined Whether the popover is currently open.
triggerId	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).

PopoverContent

Name	Type/Description
align = "center"	Align | undefined How to align the popup relative to the specified side.
alignOffset = 0	number | OffsetFunction | undefined 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. @example ```jsx <Positioner alignOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.width : anchor.height; }} /> ```
className	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.
finalFocus	boolean | RefObject<HTMLElement | null> | ((closeType: InteractionType) => boolean | void | 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, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
initialFocus	boolean | RefObject<HTMLElement | null> | ((openType: InteractionType) => boolean | void | HTMLElement | null) | undefined 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. - `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, `null` to fall back to the default behavior, or `false`/`undefined` to do nothing.
ref	((instance: HTMLDivElement | null) => void) | RefObject<HTMLDivElement> | null | undefined
render	ReactElement<any, string | 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.
side = "bottom"	Side | undefined Which side of the anchor element to align the popup against. May automatically change to avoid collisions.
sideOffset = 4	number | OffsetFunction | undefined 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. @example ```jsx <Positioner sideOffset={({ side, align, anchor, positioner }) => { return side === 'top' || side === 'bottom' ? anchor.height : anchor.width; }} /> ```
style	CSSProperties | ((state: PopoverPopupState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

PopoverDescription

Name	Type/Description
className	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.
ref	((instance: HTMLParagraphElement | null) => void) | RefObject<HTMLParagraphElement> | null | undefined
render	ReactElement<any, string | 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	CSSProperties | ((state: PopoverDescriptionState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

PopoverHeader

No documented props

PopoverTitle

Name	Type/Description
className	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.
ref	((instance: HTMLHeadingElement | null) => void) | RefObject<HTMLHeadingElement> | null | undefined
render	ReactElement<any, string | 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	CSSProperties | ((state: PopoverTitleState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.

PopoverTrigger

Name	Type/Description
className	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.
closeDelay = 0	number | undefined How long to wait before closing the popover that was opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
delay = 300	number | undefined How long to wait before the popover may be opened on hover. Specified in milliseconds. Requires the `openOnHover` prop.
handle	PopoverHandle<unknown> | undefined A handle to associate the trigger with a popover.
nativeButton = true true	boolean | undefined 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 = false	boolean | undefined Whether the popover should also open when the trigger is hovered.
payload	unknown A payload to pass to the popover when it is opened.
ref	((instance: HTMLButtonElement | null) => void) | RefObject<HTMLButtonElement> | null | undefined
render	ReactElement<any, string | 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	CSSProperties | ((state: PopoverTriggerState) => CSSProperties | undefined) | undefined Style applied to the element, or a function that returns a style object based on the component's state.