Getting Started
InstallationVersioning
Integrations
ESLintTailwind CSS
Theming, Patterns, and Pitfalls
Components
OverviewAccordionAlert Banner
AvatarBreadcrumbsButtonButton GroupCard
Beta
CheckboxCheckbox Group
CollapsibleComboboxData Grid / TableDialogDividerDrawerFile Input
Beta
Header BarIconIcon ButtonInline Icon ButtonInline Notification
LinkMenuNumber InputPaginationPassword InputPopoverProgressProgress RingRadioSegmented ControlSelectSide NavSliderStepper
Beta
SwitchSwitch Group
TabsTagText Area
Text InputToast NotificationTooltipTree

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 {PopoverModule} from "@qualcomm-ui/angular/popover"

Examples

Simple

Basic popover using the simple API with a label and child content. The anchor and trigger are supplied using directives, while the content is the default slot.

<div description="Description" label="Label" q-popover>
  <div q-popover-anchor>
    <button q-button q-popover-trigger variant="outline">Click Me</button>
  </div>
</div>

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.

<div q-popover-root>
  <div q-popover-anchor>
    <button q-button q-popover-trigger variant="outline">Click Me</button>
  </div>

  <ng-template qPortal>
    <div q-popover-positioner>
      <div q-popover-content>
        <div q-popover-arrow></div>
        <div q-popover-label>Label</div>
        <div q-popover-description>Description</div>
      </div>
    </div>
  </ng-template>
</div>

Emphasis

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

import {Component} from "@angular/core"

import {PortalDirective} from "@qualcomm-ui/angular-core/portal"
import {ButtonModule} from "@qualcomm-ui/angular/button"
import {PopoverModule} from "@qualcomm-ui/angular/popover"
import type {QdsPopoverEmphasis} from "@qualcomm-ui/qds-core/popover"

@Component({
  imports: [PopoverModule, ButtonModule, PortalDirective],
  selector: "popover-emphasis-demo",
  template: `
    <div class="flex gap-4">
      @for (emp of emphasisOptions; track emp) {
        <div q-popover-root [emphasis]="emp">
          <div q-popover-anchor>
            <button emphasis="primary" q-button q-popover-trigger>
              {{ emp }}
            </button>
          </div>

          <ng-template qPortal>
            <div q-popover-positioner>
              <div q-popover-content>
                <div q-popover-arrow></div>
                <div q-popover-label>Label</div>
                <div q-popover-description>This is a {{ emp }} popover.</div>
              </div>
            </div>
          </ng-template>
        </div>
      }
    </div>
  `,
})
export class PopoverEmphasisDemo {
  readonly emphasisOptions: QdsPopoverEmphasis[] = ["neutral", "brand"]
}

Explorer

Component Anatomy

Hover to highlight, click to view API

anchortriggerpositionercontentarrowarrow-tiplabeldescription

API

q-popover

The q-popover directive extends the q-popover-root directive with the following props:

PropType
description
Optional description text for the popover.
string
disablePortal
Set to true to disable portalling behavior for the popup content.
boolean
hideArrow
Set to true to hide the arrow element.
boolean
label
Optional label text for the popover.
string
description
Type
string
Description
Optional description text for the popover.
disablePortal
Type
boolean
Description
Set to true to disable portalling behavior for the popup content.
hideArrow
Type
boolean
Description
Set to true to hide the arrow element.
label
Type
string
Description
Optional label text for the popover.

Composite API

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

q-popover-root

PropTypeDefault
autoFocus
Whether to automatically set focus on the first focusable content within the popover when opened.
boolean
true
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 the Document in custom environments. i.e., Iframes, Electron.
() =>
| Node
| ShadowRoot
| Document
initialFocusEl
The element to focus on when the popover is opened.
() => HTMLElement
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
open
The controlled open state of the popover
boolean
persistentElements
The persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event
Array<
  () => Element
>
positioning
The options used to position the popover content.
PositioningOptions
restoreFocus
On close, restore focus to the element that triggered the open event.
boolean
true
(escapeKeyDown)
Function called when the escape key is pressed
KeyboardEvent
(focusOutside)
Function called when the focus is moved outside the component
CustomEvent<{
  event?: E
}>
(interactOutside)
Function called when an interaction happens outside the component
| CustomEvent<{event?: E}>
| CustomEvent<{event?: E}>
(openChanged)
Fired when the popover opens or closes.
{
  open: boolean
}
(pointerDownOutside)
Function called when the pointer is pressed down outside the component
CustomEvent<{
  event?: E
}>
(requestDismissed)
Function called when this layer is closed due to a parent layer being closed
CustomEvent<{
  originalIndex: number
  originalLayer: HTMLElement
  targetIndex: number
  targetLayer: HTMLElement
}>
autoFocus
Type
boolean
Description
Whether to automatically set focus on the first focusable content within the popover when opened.
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 the Document in custom environments. i.e., Iframes, Electron.
initialFocusEl
Type
() => HTMLElement
Description
The element to focus on when the popover is opened.
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
open
Type
boolean
Description
The controlled open state of the popover
persistentElements
Type
Array<
  () => Element
>
Description
The persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event
positioning
Type
PositioningOptions
Description
The options used to position the popover content.
restoreFocus
Type
boolean
Description
On close, restore focus to the element that triggered the open event.
(escapeKeyDown)
Type
KeyboardEvent
Description
Function called when the escape key is pressed
(focusOutside)
Type
CustomEvent<{
  event?: E
}>
Description
Function called when the focus is moved outside the component
(interactOutside)
Type
| CustomEvent<{event?: E}>
| CustomEvent<{event?: E}>
Description
Function called when an interaction happens outside the component
(openChanged)
Type
{
  open: boolean
}
Description
Fired when the popover opens or closes.
(pointerDownOutside)
Type
CustomEvent<{
  event?: E
}>
Description
Function called when the pointer is pressed down outside the component
(requestDismissed)
Type
CustomEvent<{
  originalIndex: number
  originalLayer: HTMLElement
  targetIndex: number
  targetLayer: HTMLElement
}>
Description
Function called when this layer is closed due to a parent layer being closed

q-popover-anchor

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

q-popover-trigger

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

q-popover-positioner

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

q-popover-content

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

q-popover-arrow

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

q-popover-arrow-tip

q-popover-label

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

q-popover-description

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

q-popover-close-trigger

PropType
id
id attribute. If omitted, a unique identifier will be generated for accessibility.)
string
id
Type
string
Description
id attribute. If omitted, a unique identifier will be generated for accessibility.)

Data Structures

PopoverPositioningOptions

PropTypeDefault
arrowPadding
The minimum padding between the arrow and the floating element's corner.
number
4
arrowSelector
CSS selector used to locate the arrow element within the floating element. Components override this with their own anatomy-namespaced selector (e.g. [data-menu-part=arrow]).
string
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.
            arrowSelector
            Type
            string
            Description
            CSS selector used to locate the arrow element within the floating element. Components override this with their own anatomy-namespaced selector (e.g. [data-menu-part=arrow]).
            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.
                      Last updated on by Olaf Kappes
                      Password Input
                      Progress
                      Examples
                      Simple
                      Composite
                      Emphasis
                      Explorer
                      API
                      q-popover
                      Composite API
                      q-popover-root
                      q-popover-anchor
                      q-popover-trigger
                      q-popover-positioner
                      q-popover-content
                      q-popover-arrow
                      q-popover-arrow-tip
                      q-popover-label
                      q-popover-description
                      q-popover-close-trigger
                      Data Structures
                      PopoverPositioningOptions
                      Copyright © 2026 QUALCOMM incorporated. All rights reserved. This site is built with QUI Docs. Head over to the template repository to start building.