Popover
<sl-popover> | SlPopover
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.
<sl-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> <sl-button variant="primary" size="small">Take Action</sl-button> </div> </sl-popover> <sl-button id="popover__overview">Show popover</sl-button>
Examples
Assigning an Anchor
Use <sl-button> or <button> elements as popover anchors. Connect the
popover to its anchor by setting the for attribute to match the anchor’s id.
<sl-button id="popover__anchor-button">Show Popover</sl-button> <sl-popover for="popover__anchor-button"> I'm anchored to a HDS button. </sl-popover> <br /><br /> <button id="popover__anchor-native-button">Show Popover</button> <sl-popover for="popover__anchor-native-button"> I'm anchored to a native button. </sl-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.
<sl-popover for="popover__opening"> <p>The button below has <code>data-popover="close"</code> so clicking it will close the popover.</p> <sl-button data-popover="close" variant="primary">Dismiss</sl-button> </sl-popover> <sl-button id="popover__opening">Show popover</sl-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.
<div style="display: flex; gap: 1rem; align-items: center;"> <sl-button id="popover__top">Top</sl-button> <sl-popover for="popover__top" placement="top">I'm on the top</sl-popover> <sl-button id="popover__bottom">Bottom</sl-button> <sl-popover for="popover__bottom" placement="bottom">I'm on the bottom</sl-popover> <sl-button id="popover__left">Left</sl-button> <sl-popover for="popover__left" placement="left">I'm on the left</sl-popover> <sl-button id="popover__right">Right</sl-button> <sl-popover for="popover__right" placement="right">I'm on the right</sl-popover> </div>
Distance
Use the distance attribute to control how far the popover appears from its anchor.
<div style="display: flex; gap: 1rem; align-items: center;"> <sl-button id="popover__distance-near">Near</sl-button> <sl-popover for="popover__distance-near" distance="0">I'm very close</sl-popover> <sl-button id="popover__distance-far">Far</sl-button> <sl-popover for="popover__distance-far" distance="30">I'm farther away</sl-popover> </div>
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.
<div style="display: flex; gap: 1rem; align-items: center;"> <sl-button id="popover__big-arrow">Big arrow</sl-button> <sl-popover for="popover__big-arrow" style="--arrow-size: 8px;">I have a big arrow</sl-popover> <sl-button id="popover__no-arrow">No arrow</sl-button> <sl-popover for="popover__no-arrow" without-arrow>I don't have an arrow</sl-popover> </div>
Setting a Maximum Width
Use the --max-width custom property to control the maximum width of the popover.
<sl-button id="popover__max-width">Toggle me</sl-button> <sl-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. </sl-popover>
Setting Focus
Use the
autofocus
global attribute to move focus to a specific form control when the popover opens.
<sl-popover for="popover__autofocus"> <div style="display: flex; flex-direction: column; gap: 1rem;"> <sl-textarea autofocus placeholder="What's on your mind?" size="small" resize="none" rows="3"></sl-textarea> <sl-button variant="primary" size="small" data-popover="close"> Submit </sl-button> </div> </sl-popover> <sl-button id="popover__autofocus"> <sl-icon name="comment" slot="start"></sl-icon> Feedback </sl-button>
[component-metadata:sl-popover]
Slots
| Name | Description |
|---|---|
| (default) | The popover’s content. Interactive elements such as buttons and links are supported. |
Learn more about using slots.
Properties
| Name | Description | Reflects | Type | Default |
|---|---|---|---|---|
placement
|
The preferred placement of the popover. Note that the actual placement may vary as needed to keep the popover inside of the viewport. |
'top' | 'top-start' | 'top-end' | 'right' | 'right-start' | 'right-end' | 'bottom' |
'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end'
|
'top'
|
|
open
|
Shows or hides the popover. |
|
boolean
|
false
|
distance
|
The distance in pixels from which to offset the popover away from its target. |
number
|
8
|
|
skidding
|
The distance in pixels from which to offset the popover along its target. |
number
|
0
|
|
for
|
The ID of the popover’s anchor element. This must be an interactive/focusable element such as a button. |
string | null
|
null
|
|
withoutArrow
without-arrow
|
Removes the arrow from the popover. |
|
boolean
|
false
|
updateComplete |
A read-only promise that resolves when the component has finished updating. |
Learn more about attributes and properties.
Events
| Name | React Event | Description | Event Detail |
|---|---|---|---|
sl-show |
|
Emitted when the popover begins to show. Canceling this event will stop the popover from showing. | - |
sl-after-show |
|
Emitted after the popover has shown and all animations are complete. | - |
sl-hide |
|
Emitted when the popover begins to hide. Canceling this event will stop the popover from hiding. | - |
sl-after-hide |
|
Emitted after the popover has hidden and all animations are complete. | - |
Learn more about events.
Methods
| Name | Description | Arguments |
|---|---|---|
show() |
Shows the popover. | - |
hide() |
Hides the popover. | - |
Learn more about methods.
Custom Properties
| Name | Description | Default |
|---|---|---|
--arrow-size |
The size of the tiny arrow that points to the popover (set to zero to remove). | 0.375rem |
--max-width |
The maximum width of the popover’s body content. | 25rem |
--z-index |
The popover’s z-index. | 1000 |
Learn more about customizing CSS custom properties.
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 <sl-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. |
Learn more about customizing CSS parts.
Dependencies
This component automatically imports the following dependencies.
<sl-popup>