Popovers

Popovers are a type of container that appear over existing content on the page. Popovers allow users to either enter additional data related to an element on a screen or view detailed content related to that element.

Available in React

When to Use
When Not to Use
Usage
- When to Include a Close Icon Button
- Behaviors
Developer Notes
Accessibility Notes

When to Use

Use a popover to create contextual relationships between a single element displayed on a screen and a more complex set of supporting content or form controls. For example, use a popover when providing additional options related to a filter.
Use to display rich text/content that you can’t fit into a tooltip.

When Not to Use

Do not use a popover for simple content such as additional help text related to a word or phrase. Instead, use a tooltip.

Usage

Popovers can be activated by a button, link, icon or form control. Unlike tooltips which display on hover for non-touch displays, popovers are invoked by clicking or tapping an element.
Popovers can be closed via a close icon, by clicking a button or clicking anywhere outside of the popover.
The amount of content in a popover should be relatively short. Consider placing longer content in a Modal.
Popovers should be positioned based on the available screen space and layout.

When to Include a Close Icon Button

While not required within a Popover, a Close Icon button provides a clear visual indicator of how a Popover can be closed. It also provides an accessible way to close the Popover if a user is navigating via keyboard or using assistive technologies. An explicit Close Icon button could be useful in the following scenarios:

The Popover contains text and no focusable elements such as buttons and form fields.
The Popover contains text and focusable elements, but non-focusable text precedes the content of the Popover, e.g header text.

Regardless of whether a Close Icon button exists within a Popover, the Spark codebase provides another way of closing the Popover by utilizing the ESC key on the keyboard.

Behaviors

When the Popover is opened, focus will be set to an element within the Popover, whether that’s the Close Icon button or another focusable element within the Popover. Refer to the Accessibility tab to learn more.

Developer Notes

Popovers are created by adding the spark-popover class to an element. The two primary components of a popover are the toggle and the content.

The toggle is used to show/hide the content and it is created by adding a class of spark-popover__toggle to an element inside the popover.

The content is created using a class of spark-popover__content--top, spark-popover__content--bottom, spark-popover__content--left or spark-popover__content--right. These different content classes determine the position of the popover.

Additionally, a list of navigation items can be defined as the content for a popover. This is done by adding the spark-popover__list class to the content and creating list items and links using the spark-popover__list-item and spark-popover__list-link classes to define menu items.

The following options may be passed when using new Spark.Popover(el, {});:

Name	Type	Default	Description
anchorX	string	'center'	The default x-axis alignment of the popover. Can also be defined using the `data-anchor-x` attribute on the popover toggle element.
anchorY	string	'bottom'	The default y-axis alignment of the popover. Can also be defined using the `data-anchor-y` attribute on the popover toggle element.
contentEl	element	null	The element to use for the popover content. This will be shown when the toggle is clicked.
toggleEl	element	null	The element to use for the popover toggle.
onOpen	function	null	A callback function run when the popover opens.
onClose	function	null	A callback function run when the popover closes.

For all available methods and full API, refer to the component code on Bitbucket.

<div class="spark-popover-group">
  <div class="spark-popover">
    <button class="spark-btn--icon spark-icon spark-icon-lock-close spark-popover__toggle" aria-label="Sign In" title="Sign In">
    </button>
    <form class="spark-popover__content col-xs-8 col-md-4" onsubmit="return false;" data-anchor-x="right" data-anchor-y="middle">
      <h4>Account Sign In</h4>
      <label class="spark-input spark-mar-t-1">
        <input class="spark-input__field" name="username" role="textbox">
        <span class="spark-label">Username</span>
      </label>
      <label class="spark-input">
        <input class="spark-input__field" name="password" type="password" role="textbox">
        <span class="spark-label">Password</span>
      </label>
      <button class="spark-btn spark-btn--md spark-btn--block">Sign In</button>
      <div class="spark-text-center spark-mar-t-1">
        <a href="#example-link" class="spark-link spark-zeta">Forgot username or password?</a>
      </div>
      <span class="spark-popover__caret"></span>
    </form>
  </div>
  <div class="spark-popover">
    <button class="spark-btn--icon spark-icon spark-icon-arrows-update-alert spark-popover__toggle" aria-label="View System Status" title="View System Status">
    </button>
    <div class="spark-popover__content" data-anchor-x="right" data-anchor-y="middle">
      <a tabindex="0" class="spark-popover__close" title="Close"></a>
      <h4>System Status</h4>
      <b>Scheduled Maintenance:</b>
      <br>Thursday, March 1 at 19:00 UTC
      <br><b>Apps and Runtime:</b>
      <br>No known issues at this time
      <br><b>Data Services:</b>
      <br>No known issues at this time
      <br>
      <br><a class="spark-mar-t-1" tabindex="0">Report an issue</a>
      <span class="spark-popover__caret"></span>
    </div>
  </div>
  <div class="spark-popover">
    <button class="spark-btn--icon spark-icon spark-icon-alert-triangle spark-popover__toggle" aria-label="Notifications" title="Notifications">
    </button>
    <div class="spark-popover__content" data-anchor-x="center" data-anchor-y="bottom">
      <a tabindex="0" aria-hidden="true" class="focus-dummy"></a>
      <b>Departure Date:</b> 04/30/2015
      <br><b>Current Loadfactor:</b> 90
      <br><b>Expected Loadfactor:</b> 95
      <br><b>Current Loadfactor LY:</b> 92
      <br><b>Final Loadfactor LY:</b> 0
      <span class="spark-popover__caret"></span>
    </div>
  </div>
  <div class="spark-popover">
    <button class="spark-btn--icon spark-icon spark-icon-cog spark-popover__toggle" aria-label="Settings" title="Settings">
    </button>
    <div class="spark-popover__content" data-anchor-x="center" data-anchor-y="top">
      <ul class="spark-popover__list">
        <li class="spark-popover__list-item">
          <a tabindex="0" class="spark-popover__list-link">Clear settings</a>
        </li>
        <li class="spark-popover__list-item">
          <a tabindex="0" class="spark-popover__list-link">Reset to defaults</a>
        </li>
        <li class="spark-popover__list-item">
          <a tabindex="0" class="spark-popover__list-link">Set as new default</a>
        </li>
      </ul>
      <span class="spark-popover__caret"></span>
    </div>
  </div>
  <div class="spark-popover">
    <button class="spark-btn--icon spark-icon spark-icon-trash spark-popover__toggle" aria-label="Delete" title="Delete">
    </button>
    <div class="spark-popover__content" role="tooltip" data-anchor-x="left" data-anchor-y="middle">
      <ul class="spark-popover__list">
        <li class="spark-popover__list-item">
          <a tabindex="0" class="spark-popover__list-link">Archive</a>
        </li>
        <li class="spark-popover__list-item">
          <a tabindex="0" class="spark-popover__list-link spark-danger">Remove forever</a>
        </li>
      </ul>
      <span class="spark-popover__caret"></span>
    </div>
  </div>
</div>

<style type="text/css">
  
  .focus-dummy {
    clip: rect(1px, 1px, 1px, 1px);
    height: 1px;
    left: 0;
    outline: 0;
    overflow: hidden;
    position: absolute !important;
    top: 0;
    width: 1px;
  }

</style>

// Vanilla JS
var el = document.querySelector('.spark-popover');
var popoverInstance = new Spark.Popover(el);

Accessibility Notes

When a Popover is opened, focus will be automatically set to the first focusable element within the Popover. Ideally this is the Close Icon button provided at the top of the Popover or another focusable element such as a link, button or form field. If none of these exist within the Popover, a visually hidden element with a tabindex attribute set to 0 can be provided. It is important that one of these options is provided within the markup of your Popover to allow assistive devices to be able to navigate the content within the Popover.

When the Tab key is used to navigate within the Popover and focus is currently on the last focusable element in the Popover, the next Tab press will set focus to the first element within the Popover. This prevents focus from being shifted to a browser button as the Popover is the last element in the DOM.

For Popovers with just text, a Close Icon button should be placed prior to the text content, and focus will be set to it when the Popover is opened. If a Close Icon button is not used in this scenario, tabindex="0" should be set to an element to allow focus to be set to it when the Popover is opened. If the Tab key is pressed, focus will be maintained on the Close Icon button or element with tabindex set as there are no other focusable elements within the Popover to navigate to.

If focusable elements are added to the Popover dynamically prior to or after it has been opened, the number of focusable elements needs to be re-parsed to ensure that keyboard tabbing accounts for these new elements. A parseFocusableElements method has been made available for this purpose.

When a Popover is closed via the ESC key or hitting the Enter key while focused on the Close Icon button, focus will be returned to the element that activated the Popover. This allows the user to continue navigating the application naturally from the point at which the Popover was opened.

Popovers

Account Sign In

System Status