Popover

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 overlayPositioning 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

3 samples
1
2
3
4
5
6
7
8
<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>
v3.0.2

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. Instead consider using a Dialog.

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 focusTrapDisabled 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

KeyFunction
TabMoves focus to next focusable element. If the current focus is the last element and focusTrapDisabled is false, focus will cycle to the first element.
Tab and ShiftMoves focus to previous focusable element. If the current focus is the first element and focusTrapDisabled is false, focus will cycle to the last element.
EscCloses the component.

API reference

Properties

PropertyAttributeDescriptionTypeDefault
autoCloseauto-closeWhen true, clicking outside of the component automatically closes open calcite-popovers.booleanfalse
closableclosableWhen true, displays a close button within the component.booleanfalse
flipDisabledflip-disabledWhen true, prevents flipping the component's placement when overlapping its referenceElement.booleanfalse
flipPlacementsSpecifies 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">
focusTrapDisabledfocus-trap-disabledWhen true, prevents focus trapping.booleanfalse
focusTrapOptionsSpecifies 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>; }
headingheadingThe component header text.string
headingLevelheading-levelSpecifies the heading level of the component's heading for proper document structure, without affecting visual styling.1 | 2 | 3 | 4 | 5 | 6
labelrequiredlabelAccessible name for the component.string
messageOverridesUse this property to override individual strings used by the component.{ close?: string; }
offsetDistanceoffset-distanceOffsets the position of the popover away from the referenceElement.number6
offsetSkiddingoffset-skiddingOffsets the position of the component along the referenceElement.number0
openopenWhen true, displays and positions the component.booleanfalse
overlayPositioningoverlay-positioningDetermines 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"
placementplacementDetermines 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"
pointerDisabledpointer-disabledWhen true, removes the caret pointer.booleanfalse
referenceElementrequiredreference-elementThe 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
scalescaleSpecifies the size of the component."l" | "m" | "s""m"
triggerDisabledtrigger-disabledWhen 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.booleanfalse

Slots

NameDescription
default (unnamed)A slot for adding custom content.

Styles

NameDescription
--calcite-popover-background-colorSpecifies the component's background color.
--calcite-popover-border-colorSpecifies the component's border color.
--calcite-popover-corner-radiusSpecifies the component's corner radius.
--calcite-popover-text-colorSpecifies the component's text color.
--calcite-popover-z-indexSpecifies the component's z-index value.

Events

NameDescriptionBehavior
calcitePopoverBeforeCloseFires when the component is requested to be closed and before the closing transition begins.bubblescomposed
calcitePopoverBeforeOpenFires when the component is added to the DOM but not rendered, and before the opening transition begins.bubblescomposed
calcitePopoverCloseFires when the component is closed and animation is complete.bubblescomposed
calcitePopoverOpenFires when the component is open and animation is complete.bubblescomposed

Methods

NameDescriptionSignature
componentOnReadyCreate a promise that resolves once component is fully loaded.componentOnReady(): Promise<void>
repositionUpdates the position of the component.reposition(delayed?: boolean): Promise<void>
setFocusSets focus on the component's first focusable element.setFocus(): Promise<void>
updateFocusTrapElementsUpdates the element(s) that are used within the focus-trap of the component.updateFocusTrapElements(): Promise<void>

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

You can no longer sign into this site. Go to your ArcGIS portal or the ArcGIS Location Platform dashboard to perform management tasks.

Your ArcGIS portal

Create, manage, and access API keys and OAuth 2.0 developer credentials, hosted layers, and data services.

Your ArcGIS Location Platform dashboard

Manage billing, monitor service usage, and access additional resources.

Learn more about these changes in the What's new in Esri Developers June 2024 blog post.

Close