Popovers are used for any contextual content that shouldn't block the the user. Some common uses are dropdown link menus, hovercards, complex tooltips, etc. Below are some guidelines for usage and structure.
A Popover, in its most basic form, looks like this.
Broken down; the first line creates the Popover container. This is where the triggering method must also be declared: click or hover. In this example, it is declared as click.
The next line creates the Popover. This is where any optional Popover paramaters can be declared. Details on the available Popover parameters are provided in the sections below.
Next, the Popover wrapper is created. This wrapper class allows optional max-height to be set on Popovers. This is especially useful for Popovers that function as dropdown menus.
Popovers don't have any padding by default, however padding can be set by nesting a divider inside of the Popover__wrapper. The contents of the Popover are contained within the divider as well.
The js-toggle-popover class must be included on the element that will trigger the Popover. In this case, it is an anchor tag.
The Popover caret it optional. Append .has-caret accordingly. Generally, carets should only be used when the triggering element (ex: the yellow button below) does not also use a caret. That will protect against potential caret alignment issues.
There are left and right positioning classes for Popovers that are top and bottom aligned. Adding a class Popover--flush-left or Popover--flush-right will adjust the Popover's positioning and transform origin accordingly. By default, Popovers are center positioned.
This is a top aligned Popover that is flushed left with the clicked element.
There are also top and bottom positioning classes for Popover that are left or right aligned. Adding classes Popover--flush-top or Popover--flush-bottom will adjust the Popover's positioning and transform origin accordingly. By default, Popovers are middle positioned.
This is a left aligned Popover that is flushed top with the clicked element.
There are 3 Popover widths: small, medium, and large. Those don't apply inner padding, but instead change the width of the overall Popover. Apply .Popover--small or .Popover--large accordingly. For medium width popoovers, omit all of the above.
Dropdown menus leverage the lists component to create a simple menu with links, possibly used for header nav menus, filters, etc. Horizontal rules can be created within dropdowns by distributing links between multiple Popover__section dividers.
Note that Popover__section dividers are only required for dropdown menu Popovers.