Popover

Description #

<vaadin-popover> is a Web Component for creating overlays that are positioned next to specified DOM element (target).

Unlike <vaadin-tooltip>, the popover supports rich content that can be provided by using renderer function.

Styling #

The following shadow DOM parts are available for styling:

Part name	Description
backdrop	Backdrop of the overlay
overlay	The overlay container
content	The overlay content
arrow	Optional arrow pointing to the target when using theme="arrow"

The following state attributes are available for styling:

Attribute	Description
position	Reflects the position property value.

Custom CSS Properties #

The following custom CSS properties are available on the <vaadin-popover> element:

Custom CSS property	Description
--vaadin-popover-offset-top	Used as an offset when the popover is aligned vertically below the target
--vaadin-popover-offset-bottom	Used as an offset when the popover is aligned vertically above the target
--vaadin-popover-offset-start	Used as an offset when the popover is aligned horizontally after the target
--vaadin-popover-offset-end	Used as an offset when the popover is aligned horizontally before the target

See Styling Components documentation.

Properties #

accessibleName #

Type: string | null | undefined

String used to label the popover to screen reader users.

accessibleNameRef #

Type: string | null | undefined

Id of the element used as label of the popover to screen reader users.

autofocus #

Type: boolean

When true, the popover content automatically receives focus after it is opened. Modal popovers use this behavior by default.

focusDelay #

Type: number

The delay in milliseconds before the popover is opened on focus when the corresponding trigger is used.

When not specified, the global default (500ms) is used.

for #

Type: string | undefined

The id of the element to be used as target value. The element should be in the DOM by the time when the attribute is set, otherwise a warning is shown.

height #

Type: string | null

Set the height of the popover. If a unitless number is provided, pixels are assumed.

hideDelay #

Type: number

The delay in milliseconds before the popover is closed on losing hover, when the corresponding trigger is used. On blur, the popover is closed immediately.

When not specified, the global default (500ms) is used.

hoverDelay #

Type: number

The delay in milliseconds before the popover is opened on hover when the corresponding trigger is used.

When not specified, the global default (500ms) is used.

modal #

Type: boolean

When true, the popover prevents interacting with background elements by setting pointer-events style on the document body to none. This also enables trapping focus inside the popover.

noCloseOnEsc #

Type: boolean

Set to true to disable closing popover on Escape press.

noCloseOnOutsideClick #

Type: boolean

Set to true to disable closing popover on outside click.

opened #

Type: boolean

True if the popover is visible and available for interaction.

overlayRole #

Type: string

The role attribute value to be set on the popover.

position #

Type: PopoverPosition

Position of the overlay with respect to the target. Supported values: top-start, top, top-end, bottom-start, bottom, bottom-end, start-top, start, start-bottom, end-top, end, end-bottom.

See also: PopoverPosition

renderer #

Type: PopoverRenderer | null | undefined

Custom function for rendering the content of the popover. Receives two arguments:

• root The root container DOM element. Append your content to it.
• popover The reference to the vaadin-popover element.

See also: PopoverRenderer

role #

Type: string | null

The role attribute value to be set on the popover. When not specified, defaults to 'dialog'.

target #

Type: HTMLElement | undefined

Reference to the DOM element used both to trigger the overlay by user interaction and to visually position it on the screen.

Defaults to an element referenced with for attribute, in which case it must be located in the same shadow scope.

trigger #

Type: PopoverTrigger[] | null | undefined

Popover trigger mode, used to configure how the popover is opened or closed. Could be set to multiple by providing an array, e.g. trigger = ['hover', 'focus'].

Supported values:

• click (default) - opens and closes on target click.
• hover - opens on target mouseenter, closes on target mouseleave. Moving mouse to the popover content keeps the popover opened.
• focus - opens on target focus, closes on target blur. Moving focus to the popover content keeps the popover opened.

In addition to the behavior specified by trigger, the popover can be closed by:

• pressing Escape key (unless noCloseOnEsc property is true)
• outside click (unless noCloseOnOutsideClick property is true)

When setting trigger property to null, undefined or empty array, the popover can be only opened programmatically by changing opened property. Note, closing on Escape press or outside click is still allowed unless explicitly disabled.

See also: PopoverTrigger

width #

Type: string | null

Set the width of the popover. If a unitless number is provided, pixels are assumed.

withBackdrop #

Type: boolean

When true, the popover has a backdrop (modality curtain) on top of the underlying page content, covering the whole viewport.

Methods #

requestContentUpdate #

Type: () => void

Requests an update for the content of the popover. While performing the update, it invokes the renderer passed in the renderer property.

It is not guaranteed that the update happens immediately (synchronously) after it is requested.

Static Methods #

setDefaultFocusDelay #

Type: (focusDelay: number) => void

Sets the default focus delay to be used by all popover instances, except for those that have focus delay configured using property.

setDefaultHideDelay #

Type: (hideDelay: number) => void

Sets the default hide delay to be used by all popover instances, except for those that have hide delay configured using property.

setDefaultHoverDelay #

Type: (hoverDelay: number) => void

Sets the default hover delay to be used by all popover instances, except for those that have hover delay configured using property.

Events #

closed #

Type: CustomEvent

Fired when the popover is closed.

opened-changed #

Type: PopoverOpenedChangedEvent

Fired when the opened property changes.

Types #

PopoverOpenedChangedEvent #

/**
 * Fired when the `opened` property changes.
 */
export type PopoverOpenedChangedEvent = CustomEvent<{ value: boolean }>;

PopoverPosition #

export type PopoverPosition =
  | 'bottom-end'
  | 'bottom-start'
  | 'bottom'
  | 'end-bottom'
  | 'end-top'
  | 'end'
  | 'start-bottom'
  | 'start-top'
  | 'start'
  | 'top-end'
  | 'top-start'
  | 'top';

PopoverRenderer #

export type PopoverRenderer = (root: HTMLElement, popover: Popover) => void;

PopoverTrigger #

export type PopoverTrigger = 'click' | 'focus' | 'hover';