Popover
Popovers display contextual content and interactive elements in a floating panel anchored to a trigger. Use them for rich tooltips, menus, or any content that appears on demand without navigating away.
Popovers display interactive content when their anchor element is clicked. Unlike tooltips, popovers can contain links, buttons, and form controls. They appear without an overlay and will close when you click outside or press Escape. Only one popover can be open at a time.
This popover contains interactive content that users can engage with directly.
Examples
Assigning an Anchor
Use <wa-button> or <button> elements as popover anchors. Connect the popover to its anchor by setting the for attribute to match the anchor's id.
Make sure the anchor element exists in the DOM before the popover connects. If it doesn't exist, the popover won't attach and you'll see a console warning.
Opening & Closing
Popovers show when you click their anchor element. You can also control them programmatically by setting the open property to true or false.
Use data-popover="close" on any button inside a popover to close it automatically.
The button below has data-popover="close" so clicking it will close the popover.
Placement
Use the placement attribute to set where the popover appears relative to its anchor. The popover will automatically reposition if there isn't enough space in the preferred location. The default placement is top.
Distance
Use the distance attribute to control how far the popover appears from its anchor.
Arrow Size
Use the --arrow-size custom property to change the size of the popover's arrow. To remove it, use the without-arrow attribute.
Setting a Maximum Width
Use the --max-width custom property to control the maximum width of the popover.
Setting Focus
Use the autofocus global attribute to move focus to a specific form control when the popover opens.
Importing
If you're using the autoloader or a hosted project, components load on demand — no manual import needed. To cherry-pick a component manually, use one of the following snippets.
Import this component directly from the CDN:
import 'https://ka-f.webawesome.com/webawesome@0.17.0/components/popover/popover.js';
After installing Web Awesome via npm, import this component:
import '@awesome.me/webawesome/dist/components/popover/popover.js';
If you're self-hosting Web Awesome, import this component from your server:
import './webawesome/dist/components/popover/popover.js';
To import this component for React 18 or below, use the following code:
import WaPopover from '@awesome.me/webawesome/dist/react/popover/index.js';
Slots
Learn more about using slots.
| Name | Description |
|---|---|
| (default) | The popover's content. Interactive elements such as buttons and links are supported. |
Attributes & Properties
Learn more about attributes and properties.
| Name | Description | Reflects |
|---|---|---|
distancedistance |
The distance in pixels from which to offset the popover away from its target.
Type
number
Default
8
|
|
forfor |
The ID of the popover's anchor element. This must be an interactive/focusable element such as a button.
Type
string | null
Default
null
|
|
openopen |
Shows or hides the popover.
Type
boolean
Default
false
|
|
placementplacement |
The preferred placement of the popover. Note that the actual placement may vary as needed to keep the popover
inside of the viewport.
Type
'top'
| 'top-start'
| 'top-end'
| 'right'
| 'right-start'
| 'right-end'
| 'bottom'
| 'bottom-start'
| 'bottom-end'
| 'left'
| 'left-start'
| 'left-end'
Default
'top'
|
|
skiddingskidding |
The distance in pixels from which to offset the popover along its target.
Type
number
Default
0
|
|
withoutArrowwithout-arrow |
Removes the arrow from the popover.
Type
boolean
Default
false
|
|
Methods
Learn more about methods.
| Name | Description | Arguments |
|---|---|---|
hide() |
Hides the popover. | |
show() |
Shows the popover. |
Events
Learn more about events.
| Name | Description |
|---|---|
wa-after-hide |
Emitted after the popover has hidden and all animations are complete. |
wa-after-show |
Emitted after the popover has shown and all animations are complete. |
wa-hide |
Emitted when the popover begins to hide. Canceling this event will stop the popover from hiding. |
wa-show |
Emitted when the popover begins to show. Canceling this event will stop the popover from showing. |
CSS Custom Properties
Learn more about CSS custom properties.
| Name | Description |
|---|---|
--arrow-size |
The size of the tiny arrow that points to the popover (set to zero to remove).
Default
0.375rem
|
--hide-duration |
The speed of the hide animation.
Default
var(--wa-transition-fast)
|
--max-width |
The maximum width of the popover's body content.
Default
25rem
|
--show-duration |
The speed of the show animation.
Default
var(--wa-transition-fast)
|
Custom States
Learn more about custom states.
| Name | Description | CSS selector |
|---|---|---|
open |
Applied when the popover is open. |
:state(open)
|
CSS Parts
Learn more about CSS parts.
| Name | Description | CSS selector |
|---|---|---|
body |
The popover's body where its content is rendered. |
::part(body)
|
dialog |
The native dialog element that contains the popover content. |
::part(dialog)
|
popup |
The internal <wa-popup> element that positions the popover. |
::part(popup)
|
popup__arrow |
The popup's exported arrow part. Use this to target the popover's arrow. |
::part(popup__arrow)
|
popup__popup |
The popup's exported popup part. Use this to target the popover's popup container. |
::part(popup__popup)
|
Dependencies
This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.