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

API

q-popover

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

PropType
Optional description text for the popover.
string
Set to true to disable portalling behavior for the popup content.
boolean
Set to true to hide the arrow element.
boolean
Optional label text for the popover.
string
Type
string
Description
Optional description text for the popover.
Type
boolean
Description
Set to true to disable portalling behavior for the popup content.
Type
boolean
Description
Set to true to hide the arrow element.
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
Whether to automatically set focus on the first focusable content within the popover when opened.
| boolean
| undefined
true
Whether to close the popover when the escape key is pressed.
boolean
true
Whether to close the popover when the user clicks outside the popover.
boolean
true
The initial open state of the popover when rendered. Use when you don't need to control the open state of the popover.
boolean
The document's text/writing direction.
'ltr' | 'rtl'
"ltr"
The style variant of the popover.
  • 'neutral': neutral overlay background with dark text.
  • 'brand': brand primary background with white text.
| 'neutral'
| 'brand'
'neutral'
A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.
() =>
| ShadowRoot
| Document
| Node
The element to focus on when the popover is opened.
() => HTMLElement | null
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
The controlled open state of the popover
boolean
The persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event
Array<
() => Element | null
>
The options used to position the popover content.
On close, restore focus to the element that triggered the open event.
boolean
true
Function called when the escape key is pressed
KeyboardEvent
Function called when the focus is moved outside the component
FocusOutsideEvent
Function called when an interaction happens outside the component
| PointerDownOutsideEvent
| FocusOutsideEvent
Fired when the popover opens or closes.
{
open: boolean
}
Function called when the pointer is pressed down outside the component
PointerDownOutsideEvent
Function called when this layer is closed due to a parent layer being closed
LayerDismissEvent
Type
| boolean
| undefined
Description
Whether to automatically set focus on the first focusable content within the popover when opened.
Type
boolean
Description
Whether to close the popover when the escape key is pressed.
Type
boolean
Description
Whether to close the popover when the user clicks outside the popover.
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.
Type
'ltr' | 'rtl'
Description
The document's text/writing direction.
Type
| 'neutral'
| 'brand'
Description
The style variant of the popover.
  • 'neutral': neutral overlay background with dark text.
  • 'brand': brand primary background with white text.
Type
() =>
| ShadowRoot
| Document
| Node
Description
A root node to correctly resolve the Document in custom environments. i.e., Iframes, Electron.
Type
() => HTMLElement | null
Description
The element to focus on when the popover is opened.
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
Type
boolean
Description
The controlled open state of the popover
Type
Array<
() => Element | null
>
Description
The persistent elements that:
- should not have pointer-events disabled
- should not trigger the dismiss event
Description
The options used to position the popover content.
Type
boolean
Description
On close, restore focus to the element that triggered the open event.
Type
KeyboardEvent
Description
Function called when the escape key is pressed
Type
FocusOutsideEvent
Description
Function called when the focus is moved outside the component
Type
| PointerDownOutsideEvent
| FocusOutsideEvent
Description
Function called when an interaction happens outside the component
Type
{
open: boolean
}
Description
Fired when the popover opens or closes.
Type
PointerDownOutsideEvent
Description
Function called when the pointer is pressed down outside the component
Type
LayerDismissEvent
Description
Function called when this layer is closed due to a parent layer being closed

q-popover-anchor

PropType
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.)

q-popover-trigger

PropType
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.)

q-popover-positioner

PropType
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.)

q-popover-content

PropType
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.)

q-popover-arrow

PropType
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.)

q-popover-arrow-tip

q-popover-label

PropType
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.)

q-popover-description

PropType
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.)

q-popover-close-trigger

PropType
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

PopoverPositioningOptions

PropTypeDefault
The minimum padding between the arrow and the floating element's corner.
number
4
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
The overflow boundary of the reference element
() =>
| 'clippingAncestors'
| Element
| Array<Element>
| {
height: number
width: number
x: number
y: number
}
CSS selector for the content element whose z-index is copied to the floating element. Falls back to the first child.
string
Whether the popover should fit the viewport.
boolean
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
Function that returns the anchor rect
(
element:
| HTMLElement
| VirtualElement
| null,
) => AnchorRect | null
The main axis offset or gap between the reference and floating element
number
2
Whether the popover should be hidden when the reference element is detached
boolean
Options to activate auto-update listeners
| boolean
| AutoUpdateOptions
true
The offset of the floating element
{
crossAxis?: number
mainAxis?: number
}
Function called when the placement is computed
(
data: ComputePositionReturn,
) => void
Function called when the floating element is positioned or not
(data: {
placed: boolean
}) => void
The virtual padding around the viewport edges to check for overflow
number
Whether the floating element can overlap the reference element
boolean
false
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'
Whether to make the floating element same width as the reference element
boolean
The secondary axis offset or gap between the reference and floating elements
number
Whether the popover should slide when it overflows.
boolean
The strategy to use for positioning
| 'absolute'
| 'fixed'
'absolute'
A callback that will be called when the popover needs to calculate its position.
(data: {
updatePosition: () => Promise<void>
}) => void | Promise<void>
Type
number
Description
The minimum padding between the arrow and the floating element's corner.
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]).
Type
() =>
| 'clippingAncestors'
| Element
| Array<Element>
| {
height: number
width: number
x: number
y: number
}
Description
The overflow boundary of the reference element
Type
string
Description
CSS selector for the content element whose z-index is copied to the floating element. Falls back to the first child.
Type
boolean
Description
Whether the popover should fit the viewport.
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.
Type
(
element:
| HTMLElement
| VirtualElement
| null,
) => AnchorRect | null
Description
Function that returns the anchor rect
Type
number
Description
The main axis offset or gap between the reference and floating element
Type
boolean
Description
Whether the popover should be hidden when the reference element is detached
Type
| boolean
| AutoUpdateOptions
Description
Options to activate auto-update listeners
Type
{
crossAxis?: number
mainAxis?: number
}
Description
The offset of the floating element
Type
(
data: ComputePositionReturn,
) => void
Description
Function called when the placement is computed
Type
(data: {
placed: boolean
}) => void
Description
Function called when the floating element is positioned or not
Type
number
Description
The virtual padding around the viewport edges to check for overflow
Type
boolean
Description
Whether the floating element can overlap the reference element
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
Type
boolean
Description
Whether to make the floating element same width as the reference element
Type
number
Description
The secondary axis offset or gap between the reference and floating elements
Type
boolean
Description
Whether the popover should slide when it overflows.
Type
| 'absolute'
| 'fixed'
Description
The strategy to use for positioning
Type
(data: {
updatePosition: () => Promise<void>
}) => void | Promise<void>
Description
A callback that will be called when the popover needs to calculate its position.
Updated by Olaf Kappes