Popovers are floating, dismissible containers for small to medium amounts of content and interactions.
Overview
Popover is useful for providing non-critical interactions in space restrained workflows, which float over other elements in the z-axis. Avoid putting large amounts of content and using scrollbars in Popovers. Popover positioning can be automatic or set manually by using the placement
or overlay
properties respectfully.
It is recommended to place Popovers shallowly in the DOM.
For minimal text-only content, consider using Tooltip. For workflows that require more space and focus, consider using Dialog.
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
<calcite-popover heading="About this data" label="About this data" reference-element="popover-button" closable>
<p>
This data was collected over a 24 hour period during which 27 volunteers surveyed the local area and collected
and reported on sightings
of non-native Blackberry.
</p>
</calcite-popover>
<calcite-button id="popover-button">Layer information</calcite-button>
Best practices
Below are important guidelines on using the Popover component.




Accessibility
Focus order
The Popover's focus will navigate content sequentially to preserve meaning and expected use in support of Success Criterion 2.4.3: Focus Order. For this reason the first element depicted visually in the Popover will recieve keyboard focus, such as the component's close button (default).
Keyboard focus
It is strongly recommended to have focusable elements cycle through Popover where focus
is false
(default) to support assistive technology users. The expected behavior for assistive technologies is while the component is open
only the contents and focusable elements are accessible.
Keyboard navigation
Key | Function |
---|---|
Tab | Moves focus to next focusable element. If the current focus is the last element and focus is false , focus will cycle to the first element. |
Tab and Shift | Moves focus to previous focusable element. If the current focus is the first element and focus is false , focus will cycle to the last element. |
Esc | Closes the component. |
API reference
Properties
Property | Attribute | Description | Type | Default |
---|---|---|---|---|
autoClose | auto-close | When true , clicking outside of the component automatically closes open calcite-popover s. | boolean | false |
closable | closable | When true , displays a close button within the component. | boolean | false |
flipDisabled | flip-disabled | When true , prevents flipping the component's placement when overlapping its referenceElement . | boolean | false |
flipPlacements | Specifies the component's fallback placement when it's initial or specified placement has insufficient space available. | Array<"top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "leading-start" | "leading" | "leading-end" | "trailing-end" | "trailing" | "trailing-start"> | ||
focusTrapDisabled | focus-trap-disabled | When true , prevents focus trapping. | boolean | false |
focusTrapOptions | Specifies custom focus trap configuration on the component, where
"allowOutsideClick " allows outside clicks,
"initialFocus" enables initial focus,
"returnFocusOnDeactivate" returns focus when not active, and
"extraContainers" specifies additional focusable elements external to the trap (e.g., 3rd-party components appending elements to the document body). | {
initialFocus?: FocusTargetOrFalse | (() => void);
returnFocusOnDeactivate?: boolean;
allowOutsideClick?: boolean | MouseEventToBoolean;
extraContainers?: string | HTMLElement | SVGElement | Array<string | HTMLElement | SVGElement>;
} | ||
heading | heading | The component header text. | string | |
headingLevel | heading-level | Specifies the heading level of the component's heading for proper document structure, without affecting visual styling. | 1 | 2 | 3 | 4 | 5 | 6 | |
label | label | Accessible name for the component. | string | |
messageOverrides | Use this property to override individual strings used by the component. | { close?: string; } | ||
offsetDistance | offset-distance | Offsets the position of the popover away from the referenceElement . | number | 6 |
offsetSkidding | offset-skidding | Offsets the position of the component along the referenceElement . | number | 0 |
open | open | When true , displays and positions the component. | boolean | false |
overlayPositioning | overlay-positioning | Determines the type of positioning to use for the overlaid content.
Using "absolute" will work for most cases. The component will be positioned inside of overflowing parent containers and will affect the container's layout.
"fixed" value should be used to escape an overflowing parent container, or when the reference element's position CSS property is "fixed" . | "absolute" | "fixed" | "absolute" |
placement | placement | Determines where the component will be positioned relative to the referenceElement . | "auto" | "auto-end" | "auto-start" | "bottom" | "bottom-end" | "bottom-start" | "leading" | "leading-end" | "leading-start" | "left" | "left-end" | "left-start" | "right" | "right-end" | "right-start" | "top" | "top-end" | "top-start" | "trailing" | "trailing-end" | "trailing-start" | "auto" |
pointerDisabled | pointer-disabled | When true , removes the caret pointer. | boolean | false |
referenceElement | reference-element | The referenceElement used to position the component according to its placement value. Setting to an HTMLElement is preferred so the component does not need to query the DOM. However, a string id of the reference element can also be used. | Element | VirtualElement | string | |
scale | scale | Specifies the size of the component. | "l" | "m" | "s" | "m" |
triggerDisabled | trigger-disabled | When true , disables automatically toggling the component when its referenceElement has been triggered.
This property can be set to true to manage when the component is open. | boolean | false |
Slots
Name | Description |
---|---|
default (unnamed) | A slot for adding custom content. |
Styles
Name | Description |
---|---|
--calcite-popover-background-color | Specifies the component's background color. |
--calcite-popover-border-color | Specifies the component's border color. |
--calcite-popover-corner-radius | Specifies the component's corner radius. |
--calcite-popover-text-color | Specifies the component's text color. |
--calcite-popover-z-index | Specifies the component's z-index value. |
Events
Name | Description | Behavior |
---|---|---|
calcitePopoverBeforeClose | Fires when the component is requested to be closed and before the closing transition begins. | |
calcitePopoverBeforeOpen | Fires when the component is added to the DOM but not rendered, and before the opening transition begins. | |
calcitePopoverClose | Fires when the component is closed and animation is complete. | |
calcitePopoverOpen | Fires when the component is open and animation is complete. |
Methods
Name | Description | Signature |
---|---|---|
componentOnReady | Create a promise that resolves once component is fully loaded. | componentOnReady(): Promise<void> |
reposition | Updates the position of the component. | reposition(delayed?: boolean): Promise<void> |
setFocus | Sets focus on the component's first focusable element. | setFocus(): Promise<void> |
updateFocusTrapElements | Updates the element(s) that are used within the focus-trap of the component. | updateFocusTrapElements(): Promise<void> |