Modals

Use modals to focus the user experience on a critical task or set of information.

Modals have simple base styling, with the contents using a semantic markup structure. You can use utility classes or your own custom CSS to style the modal content (including header, footer, and content) further.

Try to keep the modal dialog as high in the document tree as possible. While the dialog is styled in a way to make it mostly capable of being nested in divs or other wrappers, doing so comes with a risk of interfering with the fullscreen effect of the dialog.

Worth noting: there can only be one modal open at a time. Stacked modals are not supported.

Basic Modal

Check out this example modal:

<button data-target="modal-id">Open modal</button>

<div class="modal-overlay" data-modal="modal-id">
  <div class="modal-dialog" data-parent="modal-id" aria-labelledby="header-id">
    <header class="modal-header">
      <h2 class="h5 has-no-m" id="header-id">
        Modal Header
      </h2>
      <a class="has-font-size-sm" data-close href="#">
        Close
      </a>
    </header>
    <section class="modal-body">
      <p>Some modal content here</p>
    </section>
    <footer class="modal-footer">
      <a class="button has-no-m-block-end has-m-inline-end-sm" data-close href="#">
        Cancel
      </a>
      <a class="button is-primary has-no-m-block-end">
        OK
      </a>
    </footer>
  </div>
</div>

You can ditch the modal-header, modal-body, and modal-footer classes altogether if you wish to have even more control of the content. These classes are, however, customizable via Sass and should fit most common use-cases.

Long Content

The modal will be able to handle long-content with ease, turning the overlay into a scrollable area.

Dialog Positioning

By adding flex modifier classes onto the overlay, you can further stylize the positioning of the dialog.

For example, to vertically center the dialog, add the has-align-items-center class to the overlay element.

<button data-target="modal-id">Open centered modal</button>

<div class="modal-overlay is-d-flex has-align-items-center" data-modal="modal-id">
  <div class="modal-dialog" data-parent="modal-id" aria-labelledby="header-id">
    ...
  </div>
</div>

Learn more about alignment and display utilities.

Requirements

Two main pieces are required: a single line of JS and correct HTML markup.

HTML

Trigger Attributes

For the modal button, it should have two main properties:

<button data-target="modal-id">Press me</button>
  • data-target: an attribute containing a unique id pointing to the modal overlay’s data-modal attribute.

For the modal itself, you can add a few more things.

<div class="modal-overlay" data-modal="modal-id">
  <div class="modal-dialog" data-parent="modal-id" aria-labelledby="header-id">
    <header class="modal-header">
      <h2 id="header-id">
        Modal Header
      </h2>
      <a data-close href="#">
        Close
      </a>
    </header>
    <section class="modal-body">
      ...
    </section>
    <footer class="modal-footer">
      <a data-close href="#">...</a>
    </footer>
  </div>
</div>

While optional, using header and footer elements provides semantic meaning for the dialog. It’s highly recommended to use this structure.

  • data-modal: an attribute with a value matching its trigger element’s data-target attribute.
  • data-parent: an attribute pointing to the modal wrapper. It should equal the value of the element with data-modal.
  • data-close: an attribute indicating a button or link will close the active modal dialog if clicked.

Accessibility

The below attributes you should add to elements yourself. They increase the content’s accessibility for users with assistive technologies, such as screen readers.

  • aria-hidden: an attribute that should be attached to any icons (close or otherwise) in the modal, such as a “close” icon (in lieu of text). Screen readers are inconsistent with icons, so they should be hidden instead. When using an icon, make sure you have is-visually-hidden text describing the action.
  • aria-labelledby: an attribute to be attached to the modal-dialog element. It should have a matching value to the header element’s id.

See WAI-ARIA documentation on best-practices for the dialog modal UI pattern.

Styling Classes

  • modal-overlay: adds overlay styling for the modal background.
  • modal-dialog: the container for dialog content.

Edit much of the styling within _config.scss.

API

See Download documentation to see how to add the JS to your site, and JavaScript documentation to see general API details.

Call one of the following scripts from Undernet's JavaScript (not both!). This should happen only once on page load.

Undernet.start()
Undernet.Modals.start()

Alternatively, if you wish to initialize only a single component instance, you can pass a string denoting the id used in your data-modal attribute:

Undernet.Modals.start("my-id-123")

Is there information missing? Edit this page on Github!