Popover

Popover displays contextual information or actions in a floating container that appears relative to a trigger element. Unlike dialogs, popovers are non-modal and allow users to continue interacting with the background content.

import {Popover} from "@qualcomm-ui/react/popover"

Examples

Simple

Basic popover using the simple API with a label and child content.

<Popover
  label="Label"
  trigger={<Button emphasis="primary">Show Popover</Button>}
>
  Popover content
</Popover>

Composite

Build with the composite API for granular control. This API requires you to provide each subcomponent, but gives you full control over the structure and layout.

<Popover.Root>
  <Popover.Anchor>
    <Popover.Trigger>
      <Button emphasis="primary">Show Popover</Button>
    </Popover.Trigger>
  </Popover.Anchor>

  <Portal>
    <Popover.Positioner>
      <Popover.Content>
        <Popover.Arrow />
        <Popover.Label>Label</Popover.Label>
        <Popover.Description>Description</Popover.Description>
      </Popover.Content>
    </Popover.Positioner>
  </Portal>
</Popover.Root>

Emphasis

Use emphasis to control the visual style of the popover. Two emphasis options are available: neutral (default) and brand.

import type {ReactElement} from "react"

import type {QdsPopoverEmphasis} from "@qualcomm-ui/qds-core/popover"
import {Button} from "@qualcomm-ui/react/button"
import {Popover} from "@qualcomm-ui/react/popover"
import {Portal} from "@qualcomm-ui/react-core/portal"

const emphasisOptions: QdsPopoverEmphasis[] = ["neutral", "brand"]

export function PopoverEmphasisDemo(): ReactElement {
  return (
    <div className="flex gap-4">
      {emphasisOptions.map((emphasis) => (
        <Popover.Root key={emphasis} emphasis={emphasis}>
          <Popover.Anchor>
            <Popover.Trigger>
              <Button emphasis="primary">{emphasis}</Button>
            </Popover.Trigger>
          </Popover.Anchor>

          <Portal>
            <Popover.Positioner>
              <Popover.Content>
                <Popover.Arrow />
                <Popover.Label>Label</Popover.Label>
                <Popover.Description>
                  This is a {emphasis} popover.
                </Popover.Description>
              </Popover.Content>
            </Popover.Positioner>
          </Portal>
        </Popover.Root>
      ))}
    </div>
  )
}

Accessibility

The anchor element is automatically associated with the popover:
When the popover is visible, the anchor element receives the aria-controls and aria-expanded attributes.
The anchor element's aria-haspopup is always set to 'true'.
When the Popover.Label component is supplied, the overlay panel's aria-labelledby attribute is set to the id of the label.
When the Popover.Description component is supplied, the overlay panel's aria-describedby attribute is set to the id of the label.

NOTE

Don't worry about supplying id's to the label, description or popover. If these aren't provided, they'll be generated automatically.

API

The Popover extends the Popover.Root with the following props:

Prop	Type	Default
trigger ^* Render Prop. The popover trigger event handlers and attributes are applied to this element. It must forward its ref	BindingRenderProp<PopoverTriggerBindings>
anchorProps Props applied to the anchor component.	PopoverAnchorProps
arrowProps Props applied to the arrow component.	PopoverArrowProps
contentProps Props applied to the content component.	PopoverContentProps
description Optional description text for the popover.	ReactNode
descriptionProps Props applied to the description component.	PopoverDescriptionProps
hideArrow Whether to hide the arrow.	boolean	false
label Optional label text for the popover.	ReactNode
labelProps Props applied to the label component.	PopoverLabelProps
portalProps Props applied to the portal component.	{ container?: \| HTMLElement \| RefObject<HTMLElement> disabled?: boolean }
positionerProps Props applied to the positioner component.	PopoverPositionerProps

trigger

Type

BindingRenderProp<PopoverTriggerBindings>

Description

Render Prop. The popover trigger event handlers and attributes are applied to this element. It must forward its ref

anchorProps

Type

PopoverAnchorProps

Description

Props applied to the anchor component.

arrowProps

Type

PopoverArrowProps

Description

Props applied to the arrow component.

contentProps

Type

PopoverContentProps

Description

Props applied to the content component.

description

Type

ReactNode

Description

Optional description text for the popover.

descriptionProps

Type

PopoverDescriptionProps

Description

Props applied to the description component.

hideArrow

Type

boolean

Description

Whether to hide the arrow.

label

Type

ReactNode

Description

Optional label text for the popover.

labelProps

Type

PopoverLabelProps

Description

Props applied to the label component.

portalProps

Type

{
  container?:
    | HTMLElement
    | RefObject<HTMLElement>
  disabled?: boolean
}

Description

Props applied to the portal component.

positionerProps

Type

PopoverPositionerProps

Description

Props applied to the positioner component.

Composite API

Prop	Type	Default
autoFocus Whether to automatically set focus on the first focusable content within the popover when opened.	boolean	true
children React children prop.	ReactNode
closeOnEscape Whether to close the popover when the escape key is pressed.	boolean	true
closeOnInteractOutside Whether to close the popover when the user clicks outside the popover.	boolean	true
defaultOpen The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover.	boolean
dir The document's text/writing direction.	'ltr' \| 'rtl'	'ltr'
emphasis The style variant of the popover. `'neutral'`: neutral overlay background with dark text. `'brand'`: brand primary background with white text.	\| 'neutral' \| 'brand'	'neutral'
getRootNode A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.	() => \| Node \| ShadowRoot \| Document
ids The ids of the popover elements. These will be automatically generated if omitted.	Partial<{ anchor: string arrow: string closeTrigger: string content: string description: string positioner: string title: string trigger: string }>
immediate Whether to synchronize the present change immediately or defer it to the next frame	boolean
initialFocusEl The element to focus on when the popover is opened.	() => HTMLElement
lazyMount When true, the component will not be rendered in the DOM until it becomes visible or active.	boolean	false
modal Whether the popover should be modal. When set to `true`: - interaction with outside elements will be disabled - only popover content will be visible to screen readers - scrolling is blocked - focus is trapped within the popover	boolean	false
onEscapeKeyDown Function called when the escape key is pressed	( event: KeyboardEvent, ) => void
onExitComplete Function called when the animation ends in the closed state	VoidFunction
onFocusOutside Function called when the focus is moved outside the component	( event: FocusOutsideEvent, ) => void
onInteractOutside Function called when an interaction happens outside the component	( event: InteractOutsideEvent, ) => void
onOpenChange Function invoked when the popover opens or closes open:The next value of the open state.	( open: boolean, ) => void
onPointerDownOutside Function called when the pointer is pressed down outside the component	( event: PointerDownOutsideEvent, ) => void
onRequestDismiss Function called when this layer is closed due to a parent layer being closed	( event: CustomEvent<{ originalIndex: number originalLayer: HTMLElement targetIndex: number targetLayer: HTMLElement }>, ) => void
open The controlled open state of the popover	boolean
persistentElements Returns the persistent elements that: - should not have pointer-events disabled - should not trigger the dismiss event	Array< () => Element >
portalled Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content.	boolean	true
positioning The options used to position the popover content.	PopoverPositioningOptions
present Whether the node is present (controlled by the user)	boolean
restoreFocus On close, restore focus to the element that triggered the open event.	boolean	true
skipAnimationOnMount Whether to allow the initial presence animation.	boolean	false
unmountOnExit When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.	boolean	false

autoFocus

Type

boolean

Description

Whether to automatically set focus on the first focusable content within the popover when opened.

children

Type

ReactNode

Description

React children prop.

closeOnEscape

Type

boolean

Description

Whether to close the popover when the escape key is pressed.

closeOnInteractOutside

Type

boolean

Description

Whether to close the popover when the user clicks outside the popover.

defaultOpen

Type

boolean

Description

The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover.

dir

Type

'ltr' | 'rtl'

Description

The document's text/writing direction.

emphasis

Type

| 'neutral'
| 'brand'

Description

The style variant of the popover.

'neutral': neutral overlay background with dark text.
'brand': brand primary background with white text.

getRootNode

Type

() =>
| Node
| ShadowRoot
| Document

Description

A root node to correctly resolve document in custom environments. i.e., Iframes, Electron.

ids

Type

Partial<{
  anchor: string
  arrow: string
  closeTrigger: string
  content: string
  description: string
  positioner: string
  title: string
  trigger: string
}>

Description

The ids of the popover elements. These will be automatically generated if omitted.

immediate

Type

boolean

Description

Whether to synchronize the present change immediately or defer it to the next frame

initialFocusEl

Type

() => HTMLElement

Description

The element to focus on when the popover is opened.

lazyMount

Type

boolean

Description

When true, the component will not be rendered in the DOM until it becomes visible or active.

modal

Type

boolean

Description

Whether the popover should be modal. When set to true:
- interaction with outside elements will be disabled
- only popover content will be visible to screen readers
- scrolling is blocked
- focus is trapped within the popover

onEscapeKeyDown

Type

(
  event: KeyboardEvent,
) => void

Description

Function called when the escape key is pressed

onExitComplete

Type

VoidFunction

Description

Function called when the animation ends in the closed state

onFocusOutside

Type

(
  event: FocusOutsideEvent,
) => void

Description

Function called when the focus is moved outside the component

onInteractOutside

Type

(
  event: InteractOutsideEvent,
) => void

Description

Function called when an interaction happens outside the component

onOpenChange

Type

(
  open: boolean,
) => void

Description

Function invoked when the popover opens or closes

open:The next value of the open state.

onPointerDownOutside

Type

(
  event: PointerDownOutsideEvent,
) => void

Description

Function called when the pointer is pressed down outside the component

onRequestDismiss

Type

(
  event: CustomEvent<{
    originalIndex: number
    originalLayer: HTMLElement
    targetIndex: number
    targetLayer: HTMLElement
  }>,
) => void

Description

Function called when this layer is closed due to a parent layer being closed

open

Type

boolean

Description

The controlled open state of the popover

persistentElements

Type

Array<
  () => Element
>

Description

Returns the persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event

portalled

Type

boolean

Description

Whether the popover is portalled. This will proxy the tabbing behavior regardless of the DOM position of the popover content.

positioning

Type

PopoverPositioningOptions

Description

The options used to position the popover content.

present

Type

boolean

Description

Whether the node is present (controlled by the user)

restoreFocus

Type

boolean

Description

On close, restore focus to the element that triggered the open event.

skipAnimationOnMount

Type

boolean

Description

Whether to allow the initial presence animation.

unmountOnExit

Type

boolean

Description

When true, the component will be completely removed from the DOM when it becomes inactive or hidden, rather than just being hidden with CSS.

This section describes the elements of the Popover's composite API.

Prop	Type
children React children prop.	ReactNode
id id attribute. If omitted, a unique identifier will be automatically generated for accessibility.	string
render Allows you to replace the component's HTML element with a different tag or component. Learn more	\| ReactElement \| (( props: object, ) => ReactElement)

children

Type

ReactNode

Description

React children prop.

Type

string

Description

id attribute. If omitted, a unique identifier will be automatically generated for accessibility.

render

Type

| ReactElement
| ((
    props: object,
  ) => ReactElement)

Description

Allows you to replace the component's HTML element with a different tag or component. Learn more

Data Structures

Prop	Type	Default
arrowPadding The minimum padding between the arrow and the floating element's corner.	number	4
boundary The overflow boundary of the reference element	() => \| 'clippingAncestors' \| Element \| Array<Element> \| { height: number width: number x: number y: number }
fitViewport Whether the popover should fit the viewport.	boolean
flip Whether to flip the placement when the floating element overflows the boundary.	\| boolean \| Array< \| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start' >	true
getAnchorRect Function that returns the anchor rect	( element: \| HTMLElement \| VirtualElement, ) => { height?: number width?: number x?: number y?: number }
gutter The main axis offset or gap between the reference and floating element	number	8
hideWhenDetached Whether the popover should be hidden when the reference element is detached	boolean
listeners Options to activate auto-update listeners	\| boolean \| { ancestorResize?: boolean ancestorScroll?: boolean animationFrame?: boolean elementResize?: boolean layoutShift?: boolean }	true
offset The offset of the floating element	{ crossAxis?: number mainAxis?: number }
onComplete Function called when the placement is computed	( data: ComputePositionReturn, ) => void
onPositioned Function called when the floating element is positioned or not	(data: { placed: boolean }) => void
overflowPadding The virtual padding around the viewport edges to check for overflow	number
overlap Whether the floating element can overlap the reference element	boolean	false
placement The initial placement of the floating element	\| 'bottom' \| 'bottom-end' \| 'bottom-start' \| 'left' \| 'left-end' \| 'left-start' \| 'right' \| 'right-end' \| 'right-start' \| 'top' \| 'top-end' \| 'top-start'	'top'
sameWidth Whether to make the floating element same width as the reference element	boolean
shift The secondary axis offset or gap between the reference and floating elements	number
slide Whether the popover should slide when it overflows.	boolean
strategy The strategy to use for positioning	\| 'absolute' \| 'fixed'	'absolute'
updatePosition A callback that will be called when the popover needs to calculate its position.	(data: { updatePosition: () => Promise<void> }) => void \| Promise<void>

arrowPadding

Type

number

Description

The minimum padding between the arrow and the floating element's corner.

boundary

Type

() =>
| 'clippingAncestors'
| Element
| Array<Element>
| {
    height: number
    width: number
    x: number
    y: number
  }

Description

The overflow boundary of the reference element

fitViewport

Type

boolean

Description

Whether the popover should fit the viewport.

flip

Type

| boolean
| Array<
    | 'bottom'
    | 'bottom-end'
    | 'bottom-start'
    | 'left'
    | 'left-end'
    | 'left-start'
    | 'right'
    | 'right-end'
    | 'right-start'
    | 'top'
    | 'top-end'
    | 'top-start'
  >

Description

Whether to flip the placement when the floating element overflows the boundary.

getAnchorRect

Type

(
  element:
    | HTMLElement
    | VirtualElement,
) => {
  height?: number
  width?: number
  x?: number
  y?: number
}

Description

Function that returns the anchor rect

gutter

Type

number

Description

The main axis offset or gap between the reference and floating element

hideWhenDetached

Type

boolean

Description

Whether the popover should be hidden when the reference element is detached

listeners

Type

| boolean
| {
    ancestorResize?: boolean
    ancestorScroll?: boolean
    animationFrame?: boolean
    elementResize?: boolean
    layoutShift?: boolean
  }

Description

Options to activate auto-update listeners

offset

Type

{
  crossAxis?: number
  mainAxis?: number
}

Description

The offset of the floating element

onComplete

Type

(
  data: ComputePositionReturn,
) => void

Description

Function called when the placement is computed

onPositioned

Type

(data: {
  placed: boolean
}) => void

Description

Function called when the floating element is positioned or not

overflowPadding

Type

number

Description

The virtual padding around the viewport edges to check for overflow

overlap

Type

boolean

Description

Whether the floating element can overlap the reference element

placement

Type

| 'bottom'
| 'bottom-end'
| 'bottom-start'
| 'left'
| 'left-end'
| 'left-start'
| 'right'
| 'right-end'
| 'right-start'
| 'top'
| 'top-end'
| 'top-start'

Description

The initial placement of the floating element

sameWidth

Type

boolean

Description

Whether to make the floating element same width as the reference element

shift

Type

number

Description

The secondary axis offset or gap between the reference and floating elements

slide

Type

boolean

Description

Whether the popover should slide when it overflows.

strategy

Type

| 'absolute'
| 'fixed'

Description

The strategy to use for positioning

updatePosition

Type

(data: {
  updatePosition: () => Promise<void>
}) => void | Promise<void>

Description

A callback that will be called when the popover needs to calculate its position.

Tooltip