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`	Child of `.s-popover`	Used to dismiss a popover
`.s-popover--arrow`	Child of `.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"`	Controller element	Wires up the element to the popover controller. This may be a toggling element or a wrapper element.
`data-s-popover-reference-element="[css selector]"`	Controller element	Optional Designates the element to use as the popover reference. If left unset, the value defaults to the controller element.
`aria-controls="{POPOVER_ID}"`	Reference element	Associates the element to the desired popover element.
`data-action="s-popover#toggle"`	Toggling element	Wires up the element to toggle the visibility of a generic popover.
`data-s-popover-toggle-class="[class list]"`	Controller 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]"`	Controller element	Dictates where to place the popover in relation to the 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.

Events

Event	Element	Description
`s-popover:show`	Controller element	Fires immediately before showing the popover
`s-popover:shown`	Controller element	Fires immediately after showing the popover
`s-popover:hide`	Controller element	Fires immediately before hiding the popover
`s-popover:hidden`	Controller element	Fires immediately after hiding the popover

Examples

Create a team

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.

<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 positioned manually if you aren’t using the built-in JavaScript interactivity. Practically, this might look like adding something like t8 l8 to .s-popover.

Manual 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 and positioned absolutely. Adding the class .is-visible will show the popover.

If you want to set the background color to something other than the default, simply add your desired bg-* class to the s-popover element and a matching fc-* class to the s-popover--arrow element.

<div class="s-popover">
    <div class="s-popover--arrow__tc"></div>
    …
</div>

Dismissible

In the case of new feature callouts, it may be appropriate to include an explicit dismiss button. You can add one using the styling provided by .s-popover--close.

In order for to close the popover with an explicit close button, you’ll need to add the controller to a parent as illustrated in the following example code:

<div class="…"
     data-controller="s-popover"
     data-s-popover-reference-selector="#reference-element">

    <button id="reference-element" class="s-btn s-btn__filled s-btn__dropdown"
            aria-controls="popover-example"
            data-action="s-popover#toggle">
        …
    </button>

    <div id="popover-example" class="s-popover is-visible" role="menu" aria-hidden="true">
        <div class="s-popover--arrow"></div>
        <button class="s-popover--close s-btn s-btn__muted" aria-label="Close"
            data-action="s-popover#toggle">
            @Svg.ClearSm
        </button>
        …
    </div>
</div>

Hover

If the user doesn’t need to interact with the contents of the popover, it may be appropriate to only show it on hover. This will make popovers feel like a tooltip. To do so, we can rely on stock mouseover and mouseout events from Stimulus.

<button class="s-btn" role="button"
        aria-controls="popover-example"
        data-controller="s-popover"
        data-action="mouseover->s-popover#show mouseout->s-popover#hide"
        data-s-popover-placement="bottom">
    …
</button>
<div class="s-popover"
     id="popover-example"
     role="menu"
     aria-hidden="true">
    <div class="s-popover--arrow"></div>
    …
</div>