Modals

Code Examples

The Modal component is a dialog that is displayed on top of all site content. When a Modal is present, the rest of the site is inactive and covered by a mask overlay. Modals are by definition an interruption of the current user flow (they put the page into a new "mode"). Use a Modal when you need the user to enter a new flow before they continue their current task, or to provide additional contextual information about the current task. For example, you could use a modal to get confirmation from the user before deleting a record, or to display a critical error message before continuing the task at hand. Keep in mind that modals will always interrupt the current user task and should not be used if such an interruption is not desired. Research shows that mandatory interruptions are very detrimental to productivity.

Information

  • Spark Modals can be fully-controlled using a mouse, keyboard, and/or screen reader.
  • Modals can be closed by pressing the "Escape" key, clicking the Cancel button (in the Choice variant), clicking the Close icon (in the Choice or Info variants), or clicking the mask overlay (in the Choice or Info variants). Wait variant modals must be closed programatically.
  • The Modal and mask elements are hidden by default.
  • If the content in the Modal is too large for the viewport then the Modal will show a scroll bar.
  • When the Modal is opened, the first focusable element inside the Modal will receive focus.
  • While the Modal is open, focus is "trapped" inside the Modal. Pressing the Tab or Shift+Tab keys to move focus will only shift focus between the elements in the Modal.
  • When the Modal is closed, focus will be returned to the element that last had focus before the modal was opened.

Restrictions

  • The trigger element should always be outside the Modal container.
  • The data-id property is provided as a hook for automated tools. If you have multiple instances of the same variant of a component on the same page, make sure each instance has a unique data-id property ("modal-choice-1", "modal-choice-2", "modal-info-1", etc).

Configurable Variables

Variable Default Description
$sprk-modal-mask-color rgba(34, 34, 34, 0.35) Sets the color of the mask overlay that is shown behind the modal.
$sprk-modal-color $sprk-white The background color of the modal.
$sprk-modal-max-width 43.75rem The maximum width of the modal.
$sprk-modal-height 70% The maximum height of the modal.
$sprk-modal-breakpoint-small 25rem The point at which the modal moves farther down the viewport from the top.
$sprk-modal-breakpoint-medium 37.5rem The point at which the modal moves even farther down the viewport from the top.
$sprk-modal-shadow 0 4px 5px rgba(0, 0, 0, 0.6) The box-shadow on the modal.
$sprk-modal-border-radius 8px The border-radius on the modal.

Class Modifiers

Class Description
.sprk-c-Modal--wait Sets styles for the wait modal variant. Aligns items to the center.

Choice

A Choice Modal poses a question to the user and allows them to take an action.

Angular

The Modal component requires a trigger to be set up. It's typically done with a button and a (click) handler.

HTML Documentation

  • data-spark-modal-* attributes are required for Spark Modal behavior. If you would like to write your own modal behavior, you can omit these attributes.
  • Each Modal must have a unique identifier that is used for all data-spark-modal-* attributes related to that specific Modal. For example, data-sprk-modal="uniqueID" and data-sprk-modal-cancel="uniqueID".
  • The modal container HTML must be added right above the closing body tag and be outside of the main site content container.
  • The main content container of your site must have the attribute of 'data-sprk-main'.

React

  • Visibility of React modals is controlled by changing the value of the isVisible property on the modal.
<button
 class="sprk-c-Button"
 data-sprk-modal-trigger="exampleChoiceModal"
 type="button"
>
  Open Choice Modal
  </button>

  <div
   class="sprk-c-Modal sprk-u-Display--none"
   role="dialog"
   tabindex="-1"
   aria-labelledby="modalChoiceHeading"
   aria-modal="true"
   aria-describedby="modalChoiceContent"
   data-sprk-modal="exampleChoiceModal"
   data-id="modal-choice-1"
  >
    <div class="sprk-o-Stack sprk-o-Stack--large">
      <header class="sprk-o-Stack__item sprk-c-Modal__header">
        <h2
         class="sprk-c-Modal__heading sprk-b-TypeDisplayFour"
         id="modalChoiceHeading"
        >
          Are you sure?
          </h2>

          <button
           class="sprk-c-Modal__icon"
           data-sprk-modal-cancel="exampleChoiceModal"
           type="button"
           aria-label="Close Modal"
          >
            <svg
             class="sprk-c-Icon sprk-c-Icon--stroke-current-color"
             viewBox="0 0 64 64"
             aria-hidden="true"
             focusable="false"
            >
              <use xlink:href="#close"></use>
              </svg>
              </button>
      </header>

      <div class="sprk-o-Stack__item sprk-c-Modal__body">
        <p
         class="sprk-b-TypeBodyTwo"
         id="modalChoiceContent"
        >
          This is some content that is in a modal. It explains what the modal is for. There will also be a way to close the modal.
          </p>
      </div>

      <footer class="sprk-o-Stack__item">
        <button class="sprk-c-Button sprk-u-mrm">
          Confirm
        </button>

        <button
         class="sprk-c-Button sprk-c-Button--tertiary"
         data-sprk-modal-cancel="exampleChoiceModal"
        >
          Cancel
          </button>
      </footer>
    </div>
    </div>

    <div
     data-sprk-modal-mask="true"
     class="sprk-c-ModalMask sprk-u-Display--none"
     tabindex="-1"
    ></div>
          
<button
 (click)="toggleChoiceModal($event)"
 additionalClasses="choice-button"
 sprkButton
>
  Choice Modal
  </button>

  <sprk-modal
   [(isVisible)]="false"
   title="Are you sure?"
   (hide)="toggleChoiceModal($event)"
   modalType="choice"
   idString="modal-choice-1"
  >
    This is some content that is in a modal. It explains what the modal is for. There will also be a way to close the modal.
    </sprk-modal>
<script>
  // in parent component constructor
  this.state = {
    isShow: false,
  };
  // in parent component
  toggleShow = () => {
    this.setState(state => ({
      isShow: !state.isShow
    }));
  };
  <SprkModal
    title="Are you sure?"
    isVisible={this.state.isShow}
    confirmText="Confirm"
    cancelText="Cancel"
    confirmClick={() => { this.toggleShow(); }}
    cancelClick={() => { this.toggleShow(); }}
  >

    This is some content that is in a modal. It explains what the modal is for. There will also be a way to close the modal.

  </SprkModal>
  <
  SprkButton onClick = {
    () => {
      this.toggleShow();
    }
  } > Show Modal < /SprkButton>
</script>

Information

See below for available customization options:

Input Type Description
modalType string This determines the variant of the Modal. Can be 'choice', 'info', or 'wait'.
confirmText string The value supplied will be rendered as the text for the confirm button.
cancelText string The value supplied will be rendered as the text for the cancel button.
confirmAnalyticsString string The value supplied will be assigned to the 'data-analytics' attribute on the confirm button. Intended for an outside library to capture data.
idString string The value supplied will be assigned to the 'data-id' attribute on the component. This is intended to be used as a selector for automated tools. This value should be unique per page.
isVisible boolean If true, the modal will be shown. If false, the modal will not be shown.
hide function When the modal is closed the hide event is emitted and a callback function can be triggered if supplied to hide.
confirmClick function Available when the modal type is 'choice'. The modal will emit a confirm click event when the confirmation button is clicked. A callback function can be triggered if supplied to confirmClick.
cancelClick function Available when the modal type is 'choice'. The modal will emit a cancel click event when the cancel link is clicked. A callback function can be triggered if supplied to cancelClick.

Information

See below for React properties.

Property Type Description
variant string The variant to use. Can be set to choice, wait, or info. Defaults to choice.
isVisible boolean If true, the modal is visible. Defaults to false.
confirmText string This is the text on the primary action button in the modal. Defaults to "Confirm".
cancelText string This is the text on the secondary action button in the modal. Defaults to "Cancel".
confirmClick function If supplied, this function is called when the primary action button is clicked.
cancelClick function If supplied, this function is called when the secondary action button is clicked. This function is also called when the close button is clicked, when the mask overlay is clicked, or when the escape key is pressed.
title string This text is displayed in the header section of the modal.
shouldReturnFocusOnClose boolean If true, focus will automatically be returned to the last-focused item when the modal is closed. Defaults to true.
closeIcon string The icon name to use for the close button in the modal. Defaults to "close".
additionalClasses string Any additional CSS classes that should be applied to the modal.
analyticsString string The value supplied will be assigned to the data-analytics attribute on the modal.
closeAnalyticsString string The value supplied will be assigned to the data-analytics attribute on the close button (icon).
maskAnalyticsString string The value supplied will be assigned to the data-analytics attribute on the mask.
confirmAnalyticsString string The value supplied will be assigned to the data-analytics attribute on the confirm button.
cancelAnalyticsString string The value supplied will be assigned to the data-analytics attribute on the cancel button.
idString string The value supplied will be assigned to the data-id attribute on the modal.

Information

See below for HTML data attributes.

Attribute Description
data-sprk-main This attribute must be applied to the main body content container.
data-sprk-modal This attribute must be applied to the modal container and must have a value that is unique across all modals on the page.
data-sprk-modal-trigger This attribute should be placed on the element that triggers the modal to open. The value of this attribute must match the value of data-sprk-modal. Focus will be returned to this element when the modal closes.
data-sprk-modal-cancel This attribute should be placed on the Cancel button, the Close icon, and any other element that should cause the modal to close. The value of this attribute must match the value of data-sprk-modal.
data-sprk-modal-mask This attribute should be placed on the mask overlay element and should be set to true.
data-sprk-modal-trigger-prevent-default If set to true, the default click event behavior will be prevented for the element decorated with data-sprk-modal-trigger.

Info

An Info Modal shows information to the user.

Angular

To use the info modal set modalType to 'info'.

React

  • Visibility of React modals is controlled by changing the value of the isVisible property on the modal.
<button
 class="sprk-c-Button"
 data-sprk-modal-trigger="exampleInfoModal"
 type="button"
>
  Open Info Modal
  </button>

  <div
   class="sprk-c-Modal sprk-u-Display--none"
   role="dialog"
   tabindex="-1"
   aria-labelledby="modalInfoHeading"
   aria-modal="true"
   aria-describedby="modalInfoContent"
   data-sprk-modal="exampleInfoModal"
   data-id="modal-info-1"
  >
    <div class="sprk-o-Stack sprk-o-Stack--large">
      <header class="sprk-o-Stack__item sprk-c-Modal__header">
        <h2
         class="sprk-c-Modal__heading sprk-b-TypeDisplayFour"
         id="modalInfoHeading"
        >
          Info Modal
          </h2>

          <button
           class="sprk-c-Modal__icon"
           data-sprk-modal-cancel="exampleInfoModal"
           type="button"
           aria-label="Close Modal"
          >
            <svg
             class="sprk-c-Icon sprk-c-Icon--stroke-current-color"
             viewBox="0 0 64 64"
             aria-hidden="true"
             focusable="false"
            >
              <use xlink:href="#close"></use>
              </svg>
              </button>
      </header>

      <div class="sprk-o-Stack__item sprk-c-Modal__body">
        <p
         class="sprk-b-TypeBodyTwo"
         id="modalInfoContent"
        >
          This is some content that is in a Modal. It explains what the Modal is for. There will also be a way to close the modal.
          </p>
      </div>
    </div>
    </div>

    <div
     data-sprk-modal-mask="true"
     class="sprk-c-ModalMask sprk-u-Display--none"
     tabindex="-1"
    ></div>
          
<button
 (click)="toggleInfoModal($event)"
 additionalClasses="info-button"
 sprkButton
>Info Modal</button>

  <sprk-modal
   [(isVisible)]="false"
   title="For Your Information"
   (hide)="toggleInfoModal($event)"
   modalType="info"
   idString="modal-info-1"
  >
    This is some content that is in a Modal. It explains what the Modal is for. There will also be a way to close the modal.
    </sprk-modal>
<script>
  // in parent component constructor
  this.state = {
    isShow: false,
  };
  // in parent component
  toggleShow = () => {
    this.setState(state => ({
      isShow: !state.isShow
    }));
  };
</script>

...

<SprkModal
 variant="info"
 title="Info Modal"
 isVisible={this.state.isShow}
 cancelClick={()=
> { this.toggleShow(); }} > This is some content that is in a Modal. It explains what the Modal is for. There will also be a way to close the modal.

  </SprkModal>
  <SprkButton
   onClick={()=
  > { this.toggleShow(); }}>Show Modal</SprkButton>

Wait

Wait Modals display a message to the user and can only be dismissed programatically. This variant is useful for displaying loading screens.

Angular

To use the info modal set modalType to 'wait'.

React

  • Visibility of React modals is controlled by changing the value of the isVisible property on the modal.
<button
 class="sprk-c-Button"
 data-sprk-modal-trigger="exampleWaitModal"
 type="button"
>
  Open Wait Modal
  </button>

  <div
   class="sprk-c-Modal sprk-c-Modal--wait sprk-u-Display--none"
   role="dialog"
   tabindex="-1"
   aria-labelledby="modalWaitHeading"
   aria-modal="true"
   aria-describedby="modalWaitContent"
   data-sprk-modal="exampleWaitModal"
   data-sprk-modal-type="wait"
   data-id="modal-wait-1"
  >
    <div class="sprk-o-Stack sprk-o-Stack--large">
      <header class="sprk-o-Stack__item sprk-c-Modal__header">
        <h2
         class="sprk-c-Modal__heading sprk-b-TypeDisplayFour"
         id="modalWaitHeading"
        >
          Please Wait...
          </h2>
      </header>

      <div class="sprk-o-Stack__item sprk-c-Modal__body sprk-o-Stack sprk-o-Stack--medium">
        <div class="sprk-o-Stack__item sprk-c-Spinner sprk-c-Spinner--circle sprk-c-Spinner--large sprk-c-Spinner--dark"></div>
        <p
         class="sprk-o-Stack__item sprk-b-TypeBodyTwo"
         id="modalWaitContent"
        >
          This modal will close shortly for demonstration purposes.
          </p>
      </div>
    </div>
    </div>

    <div
     data-sprk-modal-mask="true"
     class="sprk-c-ModalMask sprk-u-Display--none"
     tabindex="-1"
    ></div>
          
<button
 (click)="toggleWaitModal($event)"
 additionalClasses="wait-button"
 sprkButton
>Wait Modal</button>

  <sprk-modal
   [(isVisible)]="false"
   title="Please wait..."
   (hide)="toggleWaitModal($event)"
   modalType="wait"
   idString="modal-wait-1"
  >
    This type of modal can't be closed by the user but will close shortly for demonstration purposes.
    </sprk-modal>
<script>
  // in parent component constructor
  this.state = {
    isShow: false,
  };
  // in parent component
  toggleShow = () => {
    this.setState(state => ({
      isShow: !state.isShow
    }));
  };
</script>

...

<SprkModal
 variant="wait"
 title="Please Wait..."
 isVisible={this.state.isShow}
>

  This modal will close shortly for demonstration purposes.

  </SprkModal>
  <SprkButton
   onClick={()=
  > { this.toggleShow(); }}>Show Modal</SprkButton>

Information

See below for HTML data attributes.

Attribute Description
data-sprk-modal-type Set this attribute to "wait" to enforce the correct behavior. Wait modals cannot be dismissed by pressing the Escape key or by clicking on the Mask.