Popover
Calcite Popovers are floating, dismissible containers for small to medium amounts of content and interactions.
Overview
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
Best practices
Below are important guidelines on using the Popover component.
Accessibility
Keyboard navigation
| Key | Function |
|---|---|
Tab | Move focus to next item. If the current focus is the last item, the focus will exit the component |
Tab and Shift | Move 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
Properties
| Property | Attribute | Description | Type | Values |
|---|---|---|---|---|
| autoClose | auto-close | Automatically closes any currently open popovers when clicking outside of a popover. | truefalse | |
| closeButton | close-button | Display a close button within the Popover. | truefalse | |
| disableFlip | disable-flip | Prevents flipping the popover's placement when it starts to overlap its reference element. | truefalse | |
| disablePointer | disable-pointer | Removes the caret pointer. | truefalse | |
| dismissible | dismissible | Display a close button within the Popover. | truefalse | |
| flipPlacements | Defines the available placements that can be used when a flip occurs. | ComputedPlacement[] | ||
| heading | heading | Heading text. | undefined | |
| headingLevel | heading-level | Number at which section headings should start for this component. | 123456 | |
| intlClose | intl-close | Text for close button. | "Close" (default) | |
| label | label | Accessible name for the component | undefined | |
| offsetDistance | offset-distance | Offset the position of the popover away from the reference element. | 6 (default) | |
| offsetSkidding | offset-skidding | Offset the position of the popover along the reference element. | 0 (default) | |
| open | open | Display and position the component. | truefalse | |
| overlayPositioning | overlay-positioning | Describes the type of positioning to use for the overlaid content. If your element is in a fixed container, use the 'fixed' value. | absolute (default)fixed | |
| placement | placement | Determines where the component will be positioned relative to the referenceElement. | ||
| referenceElement | reference-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. | ||
| triggerDisabled | trigger-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. | truefalse |
Events
| Name | Description | Detail |
|---|---|---|
| calcitePopoverClose | Fired when the popover is closed | any |
| calcitePopoverOpen | Fired when the popover is opened | any |
Methods
| Name | Description | Signature | Returns |
|---|---|---|---|
| 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
| Name | Description |
|---|---|
| default (unnamed) | A slot for adding custom content. |