Popovers

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.

Basic Usage

A popover, in its most basic form, looks like this. 

  <!-- A basic popover -->
  <div class="Popover-container on-click">
    <div class="Popover">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="js-toggle-popover">Click here</a>
  </div>

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. 

  <div class="Popover-container on-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. 

  <div class="Popover">

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. 

  <div class="Popover__wrapper">

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. 

  <div class="p-2">...</div>

The js-toggle-popover class must be included on the element that will trigger the popover. In this case, it is an anchor tag. 

  <a class="js-toggle-popover">Click here</a>

Triggering

Popovers can be triggered two ways: on click or hover. Click events require JavaScript. To enable click popovers, append .on-click to the .Popover-container. For hover popovers, append .on-hover instead.

This popover only activates on click.
Click popover

.on-click

This popover only activates on hover.
Hover popover

.on-hover

  <!-- Click popover -->
  <div class="Popover-container on-click">
    <div class="Popover">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Hover popover -->
  <div class="Popover-container on-hover">
    <div class="Popover">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Caret

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.

This popover does not have a caret.
Popover Without Caret
This popover has a caret.
Popover With Caret

.has-caret

  <!-- Popover with caret -->
  <div class="Popover-container on-click">
    <div class="Popover has-caret">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Alignment & Positioning

Popovers can be aligned top, right, bottom, or left. By default, they are top aligned.

Popover Alignment

This is a top aligned popover with a caret.
Top Aligned
This is a right aligned popover with a caret.
Right Aligned

.Popover--right

This is a bottom aligned popover with a caret.
Bottom Aligned

.Popover--bottom

This is a left aligned popover with a caret.
Left Aligned

.Popover--left

  <!-- Right aligned popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--right">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Bottom aligned popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--bottom">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Left aligned popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--left">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Popover Positioning

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.
Flush Left

.Popover--flush-left

This is a top aligned popover that is flushed right with the clicked element.
Flush Right

.Popover--flush-right

  <!-- Flushed left popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--flush-left">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Flushed right popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--flush-right">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

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.
Flush Top

.Popover--flush-top

This is a left aligned popover that is flushed bottom with the clicked element.
Flush Bottom

.Popover--flush-bottom

  <!-- Flushed top popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--left Popover--flush-top">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Flushed bottom popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--left Popover--flush-bottom">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Themes

There are 4 popover themes: default (light), dark, error, and success. Apply .Popover--dark, .Popover--error, or .Popover--success accordingly. Omit all of the above to use the default theme.

This is a popover using the default theme.
Default
This is a popover using the dark theme.
Dark

.Popover--dark

This is a popover using the error theme.
Error

.Popover--error

This is a popover using the success theme.
Success

.Popover--success

  <!-- Dark theme popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--dark">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Error theme popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--error">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Success theme popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--success">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Sizes

There are 5 popover sizes, numbered 1 - 5 in order of smallest to largest. They don't apply inner padding, but instead change the width of the overall popover. Apply .Popover--1, .Popover--2, etc.

This is a size 1 popover.
Size 1

.Popover--1

This is a size 2 (default) popover.
Size 2

.Popover--2

This is a size 3 popover.
Size 3

.Popover--3

This is a size 4 popover.
Size 4

.Popover--4

This is a size 5 popover.
Size 5

.Popover--5

  <!-- Size 1 popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--1">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Size 2 popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--2">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Size 3 popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--3">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Size 4 popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--4">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Size 5 popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--5">
      <div class="Popover__wrapper">
        <div class="p-2">...</div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Dropdown Menus

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.

Basic Dropdown Menu

Basic Dropdown 
  <!-- Basic dropdown menu popover -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--bottom">
      <div class="Popover__wrapper">
        <div class="Popover__section">
          <ul class="List List--padding">
            <li><a href="#">Twitter</a></li>
            <li><a href="#">Facebook</a></li>
            <li><a href="#">Google</a></li>
            <li><a href="#">Dedicated Hosting</a></li>
            <li><a href="#">Contact us</a></li>
          </ul>
        </div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Dropdown Menu With Separator

Dropdown with Separator
Dropdown with fixed separator 
  <!-- Dropdown menu popover with a separator -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--bottom">
      <div class="Popover__wrapper">
        <div class="Popover__section">
          <ul class="List List--padding">
            <li><a href="#">Twitter</a></li>
            <li><a href="#">Facebook</a></li>
            <li><a href="#">Google</a></li>
            <li><a href="#">Dedicated Hosting</a></li>
          </ul>
        </div>
        <div class="Popover__section Popover__section--separator">
          <ul class="List List--padding">
            <li><a href="#">Contact us</a></li>
          </ul>
        </div>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

  <!-- Dropdown menu popover with a fixed separator -->
  <div class="Popover-container on-click">
    <div class="Popover Popover--bottom">
      <div class="Popover__wrapper">
        <div class="Popover__section">
          <ul class="List List--padding">
            <li><a href="#">Twitter</a></li>
            <li><a href="#">Facebook</a></li>
            <li><a href="#">Google</a></li>
            <li><a href="#">Dedicated Hosting</a></li>
          </ul>
        </div>
      </div>
      <div class="Popover__section Popover__section--separator">
        <ul class="List List--padding">
          <li><a href="#">Contact us</a></li>
        </ul>
      </div>
    </div>
    <a class="Button js-toggle-popover">Click here</a>
  </div>

Product Menu

Product Menu 
  <!-- Product menu -->
  <div class="Popover-container on-click">
      <div class="Popover Popover--bottom Popover--5 Popover--flush-right">
        <div class="Popover__wrapper">
          <div class="Popover__section">
            <ul class="List List__menu List--50 List--padding">
              <li>
                <a href="#">
                  <p class="List__menu--title">Product</p>
                  <p class="List__menu--description">Product description.</p>
                </a>
              </li>
              <li>
                <a href="#">
                  <p class="List__menu--title">Product</p>
                  <p class="List__menu--description">Product description.</p>
                </a>
              </li>
            </ul>
          </div>
        </div>
      </div>
      <a class="Button js-toggle-popover has-text-caret">Product Menu</a>
    </div>
  </div>