Stacks provides a Stimulus controller that allows you to interactively display a popover from a source element. Positioning and arrow direction are managed for you by Popper.js, a powerful popover positioning library we’ve added as a dependency. These popovers are automatically hidden when user click outside the popover or tap the Esc key.

To enable interactive popovers, you will need to add the above attributes to the popover’s originating button. Custom positioning can be specified using the data-s-popover-placement. In the following example, we’ve chosen bottom-start. No positioning classes need to be added to your markup, only the data attributes.

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"
        aria-expanded="false"
        data-controller="s-popover"
        data-action="s-popover#toggle"
        data-s-popover-placement="bottom-start"
        data-s-popover-toggle-class="is-selected">
    …
</button>
<div class="s-popover"
       id="popover-example"
       role="menu">
    <div class="s-popover--arrow"></div>
    …
</div>

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"
            aria-expanded="true"
            data-action="s-popover#toggle">
        …
    </button>

    <div id="popover-example" class="s-popover is-visible" role="menu">
        <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>

There may be cases where you need to show or hide a popover via JavaScript. For example, if you need to show a popover at a specific time or if you need to hide a popover from an event outside of the controller, Stacks provides convenience methods to achieve this.

Stacks.application.register("section", class extends Stacks.StacksController {
    static targets = ["help"];

    showHelp(event) {
         Stacks.showPopover(this.helpTarget);
         event.stopPropagation();
    }
    hideHelp(event) {
         Stacks.hidePopover(this.helpTarget);
    }
});

Situations may also arise where popovers need to be attached to an element after the document is rendered. For example, a button could have a contextual menu that is too expensive to serve up on every page load.

Popovers can be attached to an element after the fact using Stacks.attachPopover.

This method takes three parameters, the element to attach the popover to, the popover either as an element or an HTML string, and optional options for displaying the popover.

Stacks.application.register("actions", class extends Stacks.StacksController {

    var loaded = false;

    async load() {
        if (this.loaded) { return; }
        Stacks.attachPopover(this.element,
                             await fetch(`/posts/{postId}/actions`),
                             { autoShow: true, toggleOnClick: true });
        this.loaded = true;
    }
});

When a popover is intended only for display as an on-hover tooltip and contains no interactive text, the s-tooltip controller can be used in place of s-popover. This is a separate controller that can be used alongside s-popover on a single target element.

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 provide an alternative controller, s-tooltip, that shows the tooltip only on hover.

In the simple case where no markup is needed in the tooltip, the popover element can be omitted and automatically generated using the title attribute.

<button class="s-btn" role="button"
        title="…"
        data-controller="s-tooltip"
        data-s-tooltip-placement="bottom-start">
    …
</button>

In cases where the tooltip needs to display simple text or HTML, the popover can be configured using JavaScript. Plain text tooltips will render characters like <, >, and & as is. HTML tooltips will render the HTML as expected.

Stacks.setTooltipText(el,
    "Plain text tooltip",
    {
        placement: "top-start"
    });

Stacks.setTooltipHtml(el,
    "Tooltip <i>with</i> HTML",
    {
        placement: "top-end"
    });

When a rich tooltip is required, a popover element can be configured in much the same way as an s-popover controller, with the most notable difference being the use of aria-describedby instead of aria-controls.

<button class="s-btn" role="button"
        aria-describedby="tooltip-example"
        aria-expanded="false"
        data-controller="s-tooltip"
        data-s-tooltip-placement="top-start">
    …
</button>
<div class="s-popover s-popover__tooltip"
     id="tooltip-example"
     role="tooltip"
     aria-hidden="true">
    <div class="s-popover--arrow"></div>
    …
</div>

Hover tooltips can be used alongside interactive popovers. Tooltips will no appear when the interactive popover is visible.

<button class="s-btn s-btn__dropdown" role="button"
        aria-controls="popover-example"
        aria-expanded="false"
        data-controller="s-popover s-tooltip"
        data-action="s-popover#toggle"
        data-s-popover-placement="bottom-start"
        data-s-popover-toggle-class="is-selected"
        title="…"
        data-s-tooltip-placement="top-start">
    …
</button>
<div class="s-popover"
       id="popover-example"
       role="menu">
    <div class="s-popover--arrow"></div>
    …
</div>

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 s-popover--arrow__tc"></div>
    …
</div>