Popover

Documentation and examples for adding CAKE popovers to any element on your site.

Overview#

CAKEs popovers rely on the 3rd party library Tippy.js in version 6.2.7.

Styling#

And you have to include the CSS from ~tippy.js/dist/tippy for basic styling. We also use a outline for the popovers. Import the ~tippy.js/dist/border for a outlined styling. And we provide a customizable theme for it. Include also the popover.scss SCSS file and you can configure the styling in variables.scss.

@import "~tippy.js/dist/tippy";
@import "~tippy.js/dist/border";

@import "~@cake/web/scss/popover";

The popover will show up by focusing/hovering above a certain element. If the element loses focus/mouseover the popover will fade out with a slight delay of 200ms. Because of the missing hover effect on handhelt devices, the popover will be shown on a click on the element. To define the content of the popover set the data-tippy-content="…" property on this element.

preview

<br />
<br />
<br />
<br />
<br />Default popover<abbr
    data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
    aria-haspopup="true" aria-expanded="false">
    <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
        focusable="false">
        <title>Default popover</title>
        <use xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
        </use>
    </svg>
</abbr>

In the examples on this page, spacing utilities are used to make the display clearer.

Placement#

You have the possibility to adjust the placement of the popover with additional data-attributes.

The popovers can be placed on any side of the dependent element. Therefore you simply have to add the data-tippy-placement attribute with one of the values top, bottom, left, right. With these configurations the popover will stick to the side you've set up, as long as there is enough space for it. Otherwise the popover will flip to the position needed.

preview

<center>
    <br />
    <br />Popover <Bottom>
        <abbr class="mb-2" data-tippy-placement="bottom"
            data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
            aria-haspopup="true" aria-expanded="false">
            <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
                focusable="false">
                <title>Default popover</title>
                <use xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                </use>
            </svg>
        </abbr>
        <br />Popover <Right>
            <abbr class="mb-2" data-tippy-placement="right"
                data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
                aria-haspopup="true" aria-expanded="false">
                <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
                    focusable="false">
                    <title>Default popover</title>
                    <use
                        xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                    </use>
                </svg>
            </abbr>
            <br />Popover <Left>
                <abbr data-tippy-placement="left"
                    data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
                    aria-haspopup="true" aria-expanded="false">
                    <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg"
                        role="img" focusable="false">
                        <title>Default popover</title>
                        <use
                            xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                        </use>
                    </svg>
                </abbr>
                <br />Popover <Top>
                    <abbr class="mb-2" data-tippy-placement="top"
                        data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
                        aria-haspopup="true" aria-expanded="false">
                        <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg"
                            role="img" focusable="false">
                            <title>Default popover</title>
                            <use
                                xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                            </use>
                        </svg>
                    </abbr>
                    <br />
                    <br />
</center>

Extended positioning#

In addition to the data-tippy-placement="{position}" you can add a suffix to the position like -start or -end. As a default the popover will be placed vertically or horizontally centerd next to the element, when there is enough space for it. If you add one of the above suffixes, you can move the popover to the edge of the start of the element (-start) or to the other edge (-end).

preview

Popover <right-start>
    <abbr class="mb-2" data-tippy-placement="right-start"
        data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
        aria-haspopup="true" aria-expanded="false">
        <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
            focusable="false">
            <title>Default popover</title>
            <use xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
            </use>
        </svg>
    </abbr>
    <br />Popover <right>
        <abbr class="mb-2" data-tippy-placement="right"
            data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
            aria-haspopup="true" aria-expanded="false">
            <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
                focusable="false">
                <title>Default popover</title>
                <use xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                </use>
            </svg>
        </abbr>
        <br />Popover <right-end>
            <abbr data-tippy-placement="right-end"
                data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
                aria-haspopup="true" aria-expanded="false">
                <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
                    focusable="false">
                    <title>Default popover</title>
                    <use
                        xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                    </use>
                </svg>
            </abbr>
            <br />Popover <top-start>
                <abbr class="mb-2" data-tippy-placement="top-start"
                    data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
                    aria-haspopup="true" aria-expanded="false">
                    <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg"
                        role="img" focusable="false">
                        <title>Default popover</title>
                        <use
                            xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                        </use>
                    </svg>
                </abbr>
                <br />> > > > > > > Popover <top>
                    <abbr class="mb-2" data-tippy-placement="top"
                        data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
                        aria-haspopup="true" aria-expanded="false">
                        <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg"
                            role="img" focusable="false">
                            <title>Default popover</title>
                            <use
                                xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                            </use>
                        </svg>
                    </abbr>
                    <br />> > > > > > > > > > > > > > > > > > > > Popover <top-end>
                        <abbr data-tippy-placement="top-end"
                            data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
                            aria-haspopup="true" aria-expanded="false">
                            <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg"
                                role="img" focusable="false">
                                <title>Default popover</title>
                                <use
                                    xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
                                </use>
                            </svg>
                        </abbr>

Contents and elements#

Despite the placement you have some more options regarding the content and the dependent element of the popover.

Custom content#

You can for example also add html-content to the popover. As default the popover content will be escaped to prevent cross-site scripting (xss) but you can enable the parsing of html-content inside the popover by setting the data-attribute data-tippy-allowHTML="true". Below there are two examples showing the possibilities of html-content inside a popover.

Keep content minimal#

Please be careful with custom content and keep it at the lowest required minimum! Otherwise the User-Experience can significantly be impaired!

preview

Popover with custom content<abbr class="mb-2" data-tippy-placement="bottom"
    data-tippy-content="&lt;h1 class=&quot;mb-1&quot;&gt;Lorem ipsum dolor sit amet&lt;/h1&gt;Consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. &lt;hr /&gt; &lt;a href=&quot;#&quot;&gt;Ut enim ad minim veniam&lt;/a&gt;, quis nostrud exercitation ullamco laboris."
    data-tippy-allowhtml="true" aria-haspopup="true" aria-expanded="false">
    <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
        focusable="false">
        <title>Default popover</title>
        <use xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
        </use>
    </svg>
</abbr>
<br />Popover with image<abbr data-tippy-placement="bottom"
    data-tippy-content="&lt;img is=&quot;rnd-img&quot; src=&quot;../../../_assets/images/examples/Backen_Weihnachten_CloseUp_v02_USAR.jpg&quot; alt=&quot;A beautiful cake image *_*&quot; class=&quot;img-fluid&quot; folder=&quot;../../../_assets/images/examples&quot; images=&quot;Apfel-Karamell-Kuchen.jpg,Apfel-Lebkuchentorte.jpg,Apfel-Quarkkuchen-mit-Sultaninen.jpg,Aprikosen-Frischkaesetorte.jpg,Aprikosengalette-mit-Rosmarin.jpg,Backen_CloseUp_v01_USAR.jpg,Backen_CloseUp_v14_USAR.jpg,Backen_Ostern_CloseUp_v02_USAR.jpg,Backen_Ostern_CloseUp_v07_USAR.jpg,Backen_Stibi_POS_WT1644_IFLA.jpg,Backen_Weihnachten_CloseUp_v02_USAR.jpg,Backen_Weihnachten_CloseUp_v14_USAR.jpg,Backen_Weihnachten_CloseUp_v16_USAR.jpg,Backen_Weihnachten_Collect_v01_USAR.jpg,Backen_Weihnachten_Recipe_Mini_Apel_Mini_Cinnamon_Cake_v02_USAR.jpg,Bellini-Torte.jpg,Birnen-Haselnuss-Streuselkuchen-mit-Cranberrys.jpg,Crepestorte.jpg,Erdbeer-Quark-Torte.jpg,Espresso-Schuettelkuchen.jpg,Espressotorte-mit-Himbeeren.jpg,Frische-Quarktorte-mit-Smoothie-Guss.jpg,Gefrorene-Brombeercharlotte.jpg,Himbeer-Eis-Guglhupf.jpg,Himbeer-Ombrecake.jpg,Japanischer-Cheesecake-mit-Erdbeeren.jpg,Johannisbeer-Pull-apart-Kuchen.jpg,Kaesekuchen-mit-Brombeeren.jpg,Kirsch-Punsch-Guglhupf.jpg,Kuhflecken-Kaesekuchen.jpg,Mangokuchen-mit-Mojito-Guss.jpg,Marzipan-Kirsch-Streifen.jpg,Orangentarte-mit-Kumquats.jpg,Pfirsichtarte-mit-Quarkcreme.jpg,Pflaumen-Pekan-Tarte.jpg,Ricottatarte-mit-Johannisbeeren.jpg,Rote-Beete-Schoko-Kuchen-mit-Schokoganache.jpg,Schoko-Espresso-Tarte.jpg,Schoko-Nougat-Guglhupf.jpg,Schokoladenkuchen-mit-Mohnsahne-und-Mango.jpg,Stollenrauten.jpg,Streusel-Kaesekuchen-mit-Blaubeeren.jpg,Walnuss-Blondies.jpg,veganer-Cheesecake-mit-Himbeeren.jpg&quot; &quot;&quot;/&gt;"
    data-tippy-allowhtml="true" data-tippy-maxwidth="500" aria-haspopup="true"
    aria-expanded="false">
    <svg class="icon icon-3 text-primary" xmlns="http://www.w3.org/2000/svg" role="img"
        focusable="false">
        <title>Default popover</title>
        <use xlink:href="../../.././_assets/images/icon__sprite.svg#questionmark-circle">
        </use>
    </svg>
</abbr>
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />
<br />

Custom elements#

As already mentioned above, you can add a popover to any valid html element. Therefore you just have to add at least the data-tippy-content to the desired element as shown below. It's recommended that you sould only use focusable elements like form elements or links in combinations with popovers to make it accessible.

preview

<button data-tippy-placement="bottom"
    data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
    aria-haspopup="true" aria-expanded="false" class="btn btn-secondary">Some button</button>
<br />
<br />
<br />
<br />
<input type="text" placeholder="Some inputfield with popover" class="form-control"
    data-tippy-placement="top"
    data-tippy-content="Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris."
    aria-haspopup="true" aria-expanded="false" />

Colors / themes#

The popover will show up in white "cake" theme as a default. The white color fits perfectly for the purpose of popovers.

Avoid usage of themes#

Since these should enable the display of further information inconspicuously, the cake theme is ideally suited by the neutral representation and you should aviod using other themes wherever it is possible.

JavaScript#

The popover does not work without javascript. You can import our javascript bundle cake.js to automatically use this feature. You only must ensure that the property data-tippy-content="…" is set on the popover element. Otherwise you can embedd the popover.js which already contains tippy.js to customize the popover options.

Initialization#

To initialize the javascript with default configuration you could simply run the following code:

document.addEventListener ('DOMContentLoaded', () => {
    window.cake.popover ();
});

Customization#

To customize the default behavior you can only embedd the popover.js file into your mockups. Then you can initialize the functionality by calling:

document.addEventListener ('DOMContentLoaded', () => {
    window.cake.popover (options = {
        popoverElements: [],
        popoverQuerySelector: '*[data-tippy-content]',
        tippyProps: {
            theme: "cake",
            placement: 'top',
            popperOptions: {
                positionFixed: true,
                modifiers: [
                    {
                        name: 'flip',
                        enabled: true,
                        options: {
                            fallbackPlacements: ['bottom'],
                        },
                    },
                ],
            },
            interactive: true,
            delay: 200,
            appendTo: 'parent',
            onMount({ reference }) {
                reference.setAttribute('aria-expanded', 'true')
            },
            onHide({ reference }) {
                reference.setAttribute('aria-expanded', 'false')
            },
        },
    });
});
  • popoverElements [Array]
    • provide the popover elements as HTMLElement (optional).
  • popoverQuerySelector [String]
    • provide a query-selector to select all popover elements. (optional, default: *[data-tippy-content]).
  • tippyProps [String]

If you do provide the options.popoverElements the options.popoverQuerySelector option gets ignored. If you do not provide any options.popoverElements always the options.popoverQuerySelector is used!

Tippy.js options (tippyProps)#

The globalConfiguration argument can be configured with any option from the Tippy.js Documentation. A full list of all the options provided by Tippy.js can be found here. The default configuration set by CAKE has been showed above.

Methods#

The popover instance provides mutliple methods, which can be used programmatically to provide you more control and possibilities. Here is the complete list of methods.

Accessibility#

The package Tippy.js provides basic functionalities to ensure basic accessibility standards. To dive deeper into that topic, you should definitely read the Accessibility section on Tippy.js.