Popovers

Popovers are small content containers that provide a contextual overlay. They can be used as in-context feature explanations, dropdowns, or tooltips.

Classes

Class Applies to Description
.s-popover N/A Base parent container for popovers
.is-visible .s-popover This class toggles the popover visibility
.s-popover--close .s-popover Used to dismiss a popover
.s-popover--arrow .s-popover When combined with JavaScript data attributes, this arrow element will be positioned automatically
.s-popover--arrow__tc .s-popover Popover arrow appears top center
.s-popover--arrow__tl .s-popover Popover arrow appears top left
.s-popover--arrow__tr .s-popover Popover arrow appears top right
.s-popover--arrow__bc .s-popover Popover arrow appears bottom center
.s-popover--arrow__bl .s-popover Popover arrow appears bottom left
.s-popover--arrow__br .s-popover Popover arrow appears bottom right
.s-popover--arrow__rc .s-popover Popover arrow appears right center
.s-popover--arrow__rt .s-popover Popover arrow appears right top
.s-popover--arrow__rb .s-popover Popover arrow appears right bottom
.s-popover--arrow__lc .s-popover Popover arrow appears left center
.s-popover--arrow__lt .s-popover Popover arrow appears left top
.s-popover--arrow__lb .s-popover Popover arrow appears left bottom

JavaScript Attributes

Attribute Applied to Description
id="{POPOVER_ID}" .s-popover A unique id that the popover’s toggling element can target. Matches the value of [aria-controls] on the toggling element.
data-controller="s-popover" Toggling element Wires up the button to the popover controller.
data-action="s-popover#toggle" Toggling element Wires up the button to toggle the visibility of a generic popover.
aria-controls="{POPOVER_ID}" Toggling element Associates the button to the desired popover element.
data-s-popover-toggle-class="[class list]" Toggling element Adds an optional space-delineated list of classes to be toggled on the originating element when the popover is shown or hidden.
data-s-popover-placement="[placement]" Toggling element Dictates where to place the popover in relation to the toggle reference element. By default, the placement value is bottom. Accepted placements are auto, top, right, bottom, left. Each placement can take an additional -start and -end variation.

Examples

Automatic

If you’ve added the proper Stimulus controllers to your popover, positioning and arrow direction will be managed for you by Popper.js, a powerful popover positioning library we’ve added as a dependency.

To promote being able to tab to an open popover, it’s best to place the popover immediately after the toggling button in the markup as siblings.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
<button class="s-btn s-btn__dropdown" role="button"
        aria-controls="popover-example"
        data-controller="s-popover"
        data-action="s-popover#toggle"
        data-s-popover-placement="bottom"
        data-s-popover-toggle-class="is-selected"></button>
<div class="s-popover"
        id="popover-example"
        role="menu"
        aria-hidden="true">
    <div class="s-popover--arrow"></div></div>

Manual

Popovers can also be positioning manually. This will most likely be achieved by adding something like ps-absolute t8 l8 to .s-popover. Manually positioning for arrows is also provided. Arrow direction (top, right, bottom, left) will appear first, followed by the secondary (center, top, right, bottom, left). For example, a popover with an arrow child of .s-popover--arrow_tc will appear on the top of the .s-popover and centered horizontally. Though there are sensible defaults applied to the width of popovers, you may need to adjust manually.

By default, popovers are hidden. Adding the class .is-visible will show the popover.

1
2
3
4
<div class="s-popover">
    <div class="s-popover--arrow__tc"></div></div>

.s-popover--arrow__tc

Popover arrow appears top center

.s-popover--arrow__tl

Popover arrow appears top left

.s-popover--arrow__tr

Popover arrow appears top right

.s-popover--arrow__bc

Popover arrow appears bottom center

.s-popover--arrow__bl

Popover arrow appears bottom left

.s-popover--arrow__br

Popover arrow appears bottom right

.s-popover--arrow__rc

Popover arrow appears right center

.s-popover--arrow__rt

Popover arrow appears right top

.s-popover--arrow__rb

Popover arrow appears right bottom

.s-popover--arrow__lc

Popover arrow appears left center

.s-popover--arrow__lt

Popover arrow appears left top

.s-popover--arrow__lb

Popover arrow appears left bottom