Popup

Popup is a small, semi-permanent context menu or dialog window that gives a user additional information and controls.

These are similar to a Dropdown but are used for data controls and they do not close when the user clicks off of them. They must be closed intentionally.

Default popup

Create a default popup using the <details> element with class .hc-popup. The toggling element must be a <summary> element and can be styled however you like. The default should just be a regular Button but it could be text or some other component.

Immediately following the <summary> toggle should be a <div> with class .hc-popup-content. We have some convenience classes below for common layouts and data types inside of popups; please use them!

HTML

Expand Edit in Playground Copy


<details class="hc-popup" name="popup1" id="popup1">
  <summary class="hc-button hc-button--primary">
    Toggle a default popup
  </summary>
  <div class="hc-popup-content">
    <details name="popup1" class="hc-popup-close">
      <summary aria-label="Close popup">
        <i class="hc-icon hc-icon--close"></i>
      </summary>
    </details>
    <div class="hc-popup-content-section hc-popup-content-section--border">
      <h5 class="hc-h5 hc-h5--no-border">
        This is the popup content.
      </h5>
    </div>
    <div class="hc-popup-content-section">
      <p>
        Here we have another section inside of the popup. Some sample form controls are below.
      </p>
    </div>
    <div class="hc-popup-content-section">
      <h6 class="hc-h6">Filters</h6>
      <div class="flex flex-col gap-2">
        <label class="hc-form-control">
          <input type="checkbox" class="hc-checkbox">
          <span class="hc-label">
              <span class="hc-label-text">Students</span>
          </span>
        </label>
        <label class="hc-form-control">
          <input type="checkbox" class="hc-checkbox">
          <span class="hc-label">
              <span class="hc-label-text">Staff members</span>
          </span>
        </label>
        <label class="hc-form-control">
          <input type="checkbox" class="hc-checkbox">
          <span class="hc-label">
              <span class="hc-label-text">Department heads</span>
          </span>
        </label>
        <label class="hc-form-control">
          <input type="checkbox" class="hc-checkbox">
          <span class="hc-label">
              <span class="hc-label-text">Parents</span>
          </span>
        </label>
      </div>
    </div>
  </div>
</details>

Close button

Importantly, popups will not close when the user clicks off of the popup content window. This behavior is expected for Dropdowns but not this Popup component. Forcing the user’s intent allows for more complex controls inside the popup and is best when more attention is needed.

The user must intentionally close the popup either by clicking the same triggering element or a close button, which you can implement either via HTML/CSS (preferred) or JS.

Adding a close button using only CSS (preferred)

Given the specific nature of the <details> element, in order to add a close button without JavaScript you must use another <details> element with the same name.

Here’s the HTML for a close button inside of a parent popup that has a name popup1:


<details name="popup1" class="hc-popup-close">
  <summary aria-label="Close popup">
    <i class="hc-icon hc-icon--close"></i>
  </summary>
</details>

Accessibility note

Since the <summary> element inside of this <details> acts as the close button and does not have any screen readable text, apply an aria-label on it that instructs the user it closes the popup.

Some additional notes and considerations on implementing the close button this way:

This second, nested <details> element should have the class .hc-popup-close and a name that is the same as the primary popup.
Add a <summary> element inside as normal, which should just have an .hc-icon--close icon inside of it.
As noted above, the <summary> should have an aria-label that identifies what it’s doing, like Close popup.
The close button is positioned absolutely to the top right of the popup’s content. Your first popup content section will automatically account for this if you’re using the .hc-popup-content-section class for that first element.

Adding a close button with JavaScript

You can always show or hide a <details> element by adding or removing the open attribute directly to the element. Create a button and place it inside of the .hc-popup-content element, and add a click handler that removes the open attribute from the primary .hc-popup element.

We do not distribute this in Honeycomb but an example would be:


<button class="hc-button hc-button--secondary" 
        onclick="document.getElementById('popup1').open = false;"
        aria-label="Close popup">
  <i class="hc-icon hc-icon--close"></i>
</button>

Close behavior on form submit

If a popup contains a form—like a table filter or some other data input that has a submit button—it’s a best practice to close the popup when that form is submitted (if the form does not reload the page). This can only be done via JavaScript and will require custom handling.

Position

Popup comes with a huge variety of positions based on your needs, relative to the triggering element or the screen itself.

Relative to the triggering element

The default position of the popup content window is that it’s pinned to the bottom left point of the triggering element, i.e., below and to the left of it.

Add modifier classes to position it one of 8 ways relative to the triggering element:

Below and to the left or right: .hc-popup--bottom-left and .hc-popup--bottom-right
Above and to the left or right: .hc-popup--top-left and .hc-popup--top-right
To the left and going up or down: .hc-popup--left-top and .hc-popup--left-bottom
To the right and going up or down: .hc-popup--right-top and .hc-popup--right-bottom

Note that some of these popups may be cut off by the bounding box due to the documentation site’s CSS. This will not be the case in-app.

Fixed to the screen

You can optionally fix larger popups to the bottom left or right of the screen, or centered like a modal if desired. Use the classes .hc-popup--screen-left, .hc-popup--screen-right, or .hc-popup--screen-center respectively.

Background overlay

You can optionally add a background overlay behind the popup by appending .hc-popup--with-overlay to the main popup element.

This should be done sparingly and with caution, as this gets to the level of “why not just use a modal?” The typical and limited use case here is when you’re pinning a popup to the bottom left or right of the screen, usually triggered from an event and not user-initiated, and you need attention.

Consider using a traditional Modal unless your use case really requires a modal-like popup.

HTML

Expand Edit in Playground Copy


<details class="hc-popup hc-popup--screen-left hc-popup--with-overlay" name="popup-slo" id="popup-slo">
  <summary class="hc-button hc-button--primary">
    Screen left with overlay
  </summary>
  <div class="hc-popup-content h-1/2">
    <details name="popup-slo" class="hc-popup-close">
      <summary aria-label="Close popup">
        <i class="hc-icon hc-icon--close"></i>
      </summary>
    </details>
    <div class="hc-popup-content-section">
      <p class="mb-4">Pinned to the bottom left of the screen.</p>
      <p class="hc-p">This popup has a manual height set on it so it doesn't look so weird.</p>
    </div>
  </div>
</details>
<details class="hc-popup hc-popup--screen-right hc-popup--with-overlay" name="popup-sro" id="popup-sro">
  <summary class="hc-button hc-button--primary">
    Screen right with overlay
  </summary>
  <div class="hc-popup-content h-1/2">
    <details name="popup-sro" class="hc-popup-close">
      <summary aria-label="Close popup">
        <i class="hc-icon hc-icon--close"></i>
      </summary>
    </details>
    <div class="hc-popup-content-section">
      <p class="mb-4">Pinned to the bottom right of the screen.</p>
      <p class="hc-p">This popup has a manual height set on it so it doesn't look so weird.</p>
    </div>
  </div>
</details>

Mobile handling

Popup has a high risk of being cut off by the edges of a small screen, which is highly unusable. For this reason, on devices at the md breakpoint and smaller, popups will always display centered on the screen and carry a max-width of 90vw.

This handling is enforced by default and no position or width class will override this behavior. Test it out with any of the popups on this page when using a mobile device or shrinking the browser window.

Design considerations and best practices

The primary design consideration with Popup is when to use it instead of Modal or Dropdown. The main differences to help guide your determination:

Modal is used to prompt the user for input or to display critical information that requires the user’s attention. For instance, a modal might be used to ask the user to confirm an action or contain a form.
Dropdown presents a context menu or a brief extended description, and closes whenever the user clicks outside of the element.
Popup presents longer form content that doesn’t require user input or complex data inputs. It also requires an intentional close, so it will not close automatically while data might be pending. Best use cases include filters (that don’t rise to the level of Drawer!), small forms, or a notice that doesn’t command as much focus as a modal.