Popover

<wa-popover> Since 3.0 stable

Popovers display contextual content and interactive elements in a floating panel.

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.

Take Action
Show popover 
<wa-popover for="popover__overview">
  <div style="display: flex; flex-direction: column; gap: 1rem;">
    <p>This popover contains interactive content that users can engage with directly.</p>
    <wa-button variant="primary" size="small">Take Action</wa-button>
  </div>
</wa-popover>

<wa-button id="popover__overview">Show popover</wa-button>

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.

Show Popover I'm anchored to a Web Awesome button.

I'm anchored to a native button. 
<wa-button id="popover__anchor-button">Show Popover</wa-button>

<wa-popover for="popover__anchor-button"> I'm anchored to a Web Awesome button. </wa-popover>

<br /><br />

<button id="popover__anchor-native-button">Show Popover</button>

<wa-popover for="popover__anchor-native-button"> I'm anchored to a native button. </wa-popover>

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 and 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.

Dismiss Show popover 
<wa-popover for="popover__opening">
  <p>The button below has <code>data-popover="close"</code> so clicking it will close the popover.</p>
  <wa-button data-popover="close" variant="primary">Dismiss</wa-button>
</wa-popover>

<wa-button id="popover__opening">Show popover</wa-button>

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.

Top I'm on the top Bottom I'm on the bottom Left I'm on the left Right I'm on the right 
<div style="display: flex; gap: 1rem; align-items: center;">
  <wa-button id="popover__top">Top</wa-button>
  <wa-popover for="popover__top" placement="top">I'm on the top</wa-popover>

  <wa-button id="popover__bottom">Bottom</wa-button>
  <wa-popover for="popover__bottom" placement="bottom">I'm on the bottom</wa-popover>

  <wa-button id="popover__left">Left</wa-button>
  <wa-popover for="popover__left" placement="left">I'm on the left</wa-popover>

  <wa-button id="popover__right">Right</wa-button>
  <wa-popover for="popover__right" placement="right">I'm on the right</wa-popover>
</div>

Distance

Use the distance attribute to control how far the popover appears from its anchor.

Near I'm very close Far I'm farther away 
<div style="display: flex; gap: 1rem; align-items: center;">
  <wa-button id="popover__distance-near">Near</wa-button>
  <wa-popover for="popover__distance-near" distance="0">I'm very close</wa-popover>

  <wa-button id="popover__distance-far">Far</wa-button>
  <wa-popover for="popover__distance-far" distance="30">I'm farther away</wa-popover>
</div>

Arrow Size

Use the --arrow-size custom property to change the size of the popover's arrow. Set it to 0 to remove the arrow entirely.

Big arrow I have a big arrow No arrow I don't have an arrow 
<div style="display: flex; gap: 1rem; align-items: center;">
  <wa-button id="popover__big-arrow">Big arrow</wa-button>
  <wa-popover for="popover__big-arrow" style="--arrow-size: 8px;">I have a big arrow</wa-popover>

  <wa-button id="popover__no-arrow">No arrow</wa-button>
  <wa-popover for="popover__no-arrow" style="--arrow-size: 0;">I don't have an arrow</wa-popover>
</div>

Setting a Maximum Width

Use the --max-width custom property to control the maximum width of the popover.

Toggle me Popovers will usually grow to be much wider, but this one has a custom max width that forces text to wrap. 
<wa-button id="popover__max-width">Toggle me</wa-button>
<wa-popover for="popover__max-width" style="--max-width: 160px;">
  Popovers will usually grow to be much wider, but this one has a custom max width that forces text to wrap.
</wa-popover>

Setting Focus

Use the autofocus global attribute to move focus to a specific form control when the popover opens.

Submit
Feedback 
<wa-popover for="popover__autofocus">
  <div style="display: flex; flex-direction: column; gap: 1rem;">
    <wa-textarea autofocus placeholder="What's on your mind?" size="small" resize="none" rows="3"></wa-textarea>
    <wa-button variant="primary" size="small" data-popover="close"> Submit </wa-button>
  </div>
</wa-popover>

<wa-button id="popover__autofocus">
  <wa-icon name="comment" slot="start"></wa-icon>
  Feedback
</wa-button>

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
placement
placement
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'
open
open
Shows or hides the popover.
Type boolean
Default false
distance
distance
The distance in pixels from which to offset the popover away from its target.
Type number
Default 8
skidding
skidding
The distance in pixels from which to offset the popover along its target.
Type number
Default 0
for
for
The ID of the popover's anchor element. This must be an interactive/focusable element such as a button.
Type string | null
Default null

Methods

Learn more about methods.

Name Description Arguments
show() Shows the popover.
hide() Hides the popover.

Events

Learn more about events.

Name Description
wa-show Emitted when the popover begins to show. Canceling this event will stop the popover from showing.
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-after-hide Emitted after the popover has hidden and all animations are complete.

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
--max-width
The maximum width of the popover's body content.
Default 25rem
--show-duration
The speed of the show animation.
Default 100ms
--hide-duration
The speed of the hide animation.
Default 100ms

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
dialog The native dialog element that contains the popover content.
body The popover's body where its content is rendered.
popup The internal <wa-popup> element that positions the popover.
popup__popup The popup's exported popup part. Use this to target the popover's popup container.
popup__arrow The popup's exported arrow part. Use this to target the popover's arrow.

Dependencies

This component automatically imports the following elements. Sub-dependencies, if any exist, will also be included in this list.

Importing

The autoloader is the recommended way to import components. If you prefer to do it manually, use one of the following code snippets.

CDN npm React

To manually import this component from the CDN, use the following code. 

import 'https://early.webawesome.com/[email protected]/dist/components/popover/popover.js';

To manually import this component from NPM, use the following code. 

import '@awesome.me/webawesome/dist/components/popover/popover.js';

To manually import this component from React, use the following code. 

import '@awesome.me/webawesome/dist/react/popover';
Need a hand? Report a bug Ask for help
    No results