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 {ButtonModule} from "@qualcomm-ui/angular/button"
import {PopoverModule} from "@qualcomm-ui/angular/popover"
import {PortalDirective} from "@qualcomm-ui/angular-core/portal"
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"]
}

API

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

Prop	Type
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

Prop	Type	Default
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

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

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

Type

string

Description

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

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