Popover

Calcite Popovers are floating, dismissible containers for small to medium amounts of content and interactions.

Overview

Popover Manager was deprecated in beta.82. In earlier releases, Popover must have a parent element of Popover Manager.

Popovers are essentially empty-slot components designed to be invoked from an action and float over other elements in the z-axis. Popovers should be used for non-critical interactions that alleviate space restrained workflows. Avoid putting large amounts of content in a Popover and avoid scrollbars in Popovers.

Popover positioning can be automatic or manually set to avoid clipping in the interface.

For minimal text-only content, consider using Tooltip.

For workflows that require more space and focus, consider using Modal.

Usage

  • Secondary workflow support that can be invoked from an action
  • Descriptions of content
  • A few contextual actions or inputs to modify an element
  • Clicking an element to show date, author, or other relevant details

Sample

Show code snippetCopy code snippet
Edit sample on Codepen
v1.0.0-beta.83
Toggle preview themeToggle preview direction

Best practices

Below are important guidelines on using the Popover component.

Correct Popover content length
Do use Popovers for small to medium amounts of content.
Avoid Popover content length
Avoid using Popovers for one sentence of copy or less. Defer to using Tooltip for shorter copy.
Correct Popover workflows
Do use Popovers for small, focused workflows.
Avoid Popover workflows
Avoid using Popovers for complex workflows.

Accessibility

Keyboard navigation

KeyFunction
TabMove focus to next item. If the current focus is the last item, the focus will exit the component
Tab and ShiftMove focus to previous item. If the current focus is the first item, the focus will exit the component

Writing and copy

Ideally Popover text should be short and to the point, supporting the content where it was invoked from. There are cases where an important paragraph of text can be beneficial in a Popover, but avoid a scrolling frame. For longer content, please consider Modal.

  • Recommended character maximum: 450

API reference

calcite-popover
v1.0.0-beta.83

Properties

PropertyAttributeDescriptionTypeValues
autoCloseauto-close

Automatically closes any currently open popovers when clicking outside of a popover.

booleanA boolean property should be present, or not
truefalse
closeButtonclose-button
deprecateduse dismissible instead.

Display a close button within the Popover.

booleanA boolean property should be present, or not
truefalse
disableFlipdisable-flip

Prevents flipping the popover's placement when it starts to overlap its reference element.

booleanA boolean property should be present, or not
truefalse
disablePointerdisable-pointer

Removes the caret pointer.

booleanA boolean property should be present, or not
truefalse
dismissibledismissible

Display a close button within the Popover.

booleanA boolean property should be present, or not
truefalse
flipPlacements

Defines the available placements that can be used when a flip occurs.

optional
typedChoose from a set of typed values
ComputedPlacement[]
headingheading

Heading text.

optional
stringA custom string
undefined
headingLevelheading-level

Number at which section headings should start for this component.

typedChoose from a set of typed values
123456
intlCloseintl-close

Text for close button.

stringA custom string
"Close" (default)
labellabel

Accessible name for the component

required
stringA custom string
undefined
offsetDistanceoffset-distance

Offset the position of the popover away from the reference element.

numberA number
6 (default)
offsetSkiddingoffset-skidding

Offset the position of the popover along the reference element.

numberA number
0 (default)
openopen

Display and position the component.

booleanA boolean property should be present, or not
truefalse
overlayPositioningoverlay-positioning

Describes the type of positioning to use for the overlaid content. If your element is in a fixed container, use the 'fixed' value.

typedChoose from a set of typed values
absolute (default)fixed
placementplacement

Determines where the component will be positioned relative to the referenceElement.

typedChoose from a set of typed values
View documentation
referenceElementreference-element

Reference HTMLElement used to position this component according to the placement property. As a convenience, a string ID of the reference element can be used. However, setting this property to use an HTMLElement is preferred so that the component does not need to query the DOM for the referenceElement.

required
elementAn element
triggerDisabledtrigger-disabled

Disables automatically toggling a popover when its referenceElement has been triggered. This property can be set to true to manage when a popover is open.

booleanA boolean property should be present, or not
truefalse

Events

NameDescriptionDetail
calcitePopoverClose

Fired when the popover is closed

bubblescomposedcancelable
any
calcitePopoverOpen

Fired when the popover is opened

bubblescomposedcancelable
any

Methods

NameDescriptionSignatureReturns
reposition

Updates the position of the component.

reposition() => Promise<void>Promise<void>
setFocus

Sets focus on the component.

setFocus(focusId?: "close-button") => Promise<void>Promise<void>
toggle

Toggles the popover's open property.

toggle(value?: boolean) => Promise<void>Promise<void>

Slots

NameDescription
default (unnamed)

A slot for adding custom content.

Your browser is no longer supported. Please upgrade your browser for the best experience. See our browser deprecation post for more details.