Messages

Page-Level Success Message Example

Examples

• Page-Level Messages: Success, Warning, Error, Info.
• Container-Level Messages: Success, Warning, Error, Info.
• Field-Level Messages

Animations

• For added visual prominence, Messages may be configured to animate into view, adding a spark-message--animate class.
• Messages can animate on page load or when they are added to the page layout.
• For repetitious, site-wide messaging, such as System Maintenance announcements, animate only the first instance of the message per session.

Sequencing and Timing

• Limit the number of Messaging animations on a single page, to reduce visual noise.
• When animating multiple messages on a single page, sequence the messages according to priority, with Page-Level Messages highest and animating first. Messaging animations should follow a staggered approach, beginning with the first animation and starting the next animation 100 milliseconds before the end of the previous animation.

Examples

There are three locations for Messages: Page-Level (top of screen), Container-Level (top of panel) and Field-Level (below field).

Page-Level Messages

Page-Level Messages appear at the top of the page and are used for messages pertaining to the overall page content.

Success

When to Use

• Use Success Messaging to inform the user that they have corrected information that was previously causing an error to display.
• Success Messaging may also be to confirm that a requested action was completed.
• Use Success Messaging to provide encouragement to users when appropriate.

Warning

When to Use

• Use Warning Messages to communicate problems that may affect the user’s experience.
• Use Warning Messages when the user has made selections that appear to be incorrect or in conflict with other data.

Error

When to Use

• Use Error Messages to communicate problems that require the user to correct information before moving forward. For real-time messaging, display errors in the context of the field itself. For server-side messaging, it is recommended that a message appear at the top of the screen and at the field level. Shorter forms may omit the top-of-screen message as long as the required action is very apparent to the user.
• Error Messages may also be used to communicate system errors that prevent the user from proceeding down the current path.

Info

When to Use

• Use Info Messages to communicate information that does not have an explicit positive or negative association. These are most often displayed in the context of an overall screen or panel, rather than at a field level.

Container-Level Messages

Container-Level Messages appear within a panel, tabbed set or other content container.

Success

Warning

Error

Info

Field-Level Messages

Field-Level Messages appear within a form element and communicates validation information. See the specific form elements for details about field-level validation:

• Text Input
• Select
• Checkboxes
• Radio Buttons

Developer Notes

Messages are created by adding the spark-message class to an element. For Container-Level Messages, there should be an icon with the class of spark-message__icon and a content element with the class of spark-message__content. These are displayed horizontally using flexbox.

For Page-Level Messages, a class of spark-message--lg should be added. This will increase the size of the icon. Larger message heading text can be created by adding the spark-message__heading class.

Animations

Animations can be applied to either Page-Level Messages or Container-Level Messages. Add the class spark-message--animate to the spark-message element before adding the message node is added to the page.

Page-Level Messages

<div class="spark-message spark-message--lg spark-message--success spark-panel spark-message--animate">
  <div class="spark-panel__content">
    <i aria-hidden="true" class="spark-message__icon spark-icon-check spark-icon--fill"></i>
    <div class="spark-message__content">
      <h4 class="spark-message__heading">
        Success-style message title
      </h4>
      <p>
        Some message to explain in further detail.
      </p>
    </div>
  </div>
</div>

<style type="text/css">
  
</style>

<div class="spark-mar-t-1 spark-clearfix">
  <button class="spark-btn spark-btn--xs spark-btn--secondary spark-pull-right" id="button">Replay Animation</button>
</div>

Container-Level Messages

<div class="spark-message spark-message--success spark-message--animate">
  <i aria-hidden="true" class="spark-message__icon spark-icon-check spark-icon--fill"></i>
  <p class="spark-message__content">
    <b>Success-style message title.</b> Some message to explain in further detail.
  </p>
</div>

<style type="text/css">
  
</style>

<div class="spark-mar-t-1 spark-clearfix">
  <button class="spark-btn spark-btn--xs spark-btn--secondary spark-pull-right" id="button">Replay Animation</button>
</div>

Grouped Page-Level Messages

<div class="spark-panel spark-message-panel spark-message--animate">

  <div class="spark-message spark-message--lg spark-message--warning spark-panel spark-message--animate">
    <div class="spark-panel__content">
      <i aria-hidden="true" class="spark-message__icon spark-icon-alert-triangle spark-icon--fill"></i>
      <div class="spark-message__content">
        <h4 class="spark-message__heading">
          Passport About to Expire
        </h4>
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sed aliquet elit.
        </p>
      </div>
    </div>
  </div>

  <div class="spark-message spark-message--lg spark-message--success spark-panel spark-message--animate">
    <div class="spark-panel__content">
      <i aria-hidden="true" class="spark-message__icon spark-icon-check spark-icon--fill"></i>
      <div class="spark-message__content">
        <h4 class="spark-message__heading">
          Settings Saved
        </h4>
        <p>
          Lorem ipsum dolor sit amet, consectetur adipiscing elit. In sed aliquet elit.
        </p>
      </div>
    </div>
  </div>

</div>

<style type="text/css">
  
</style>

<div class="spark-mar-t-1 spark-clearfix">
<button class="spark-btn spark-btn--xs spark-btn--secondary spark-pull-right" id="button">Replay Animation</button>
</div>

Message Types

• Add a class of spark-message--success to display a Success Message.
• Add a class of spark-message--warning to display a Warning Message.
• Add a class of spark-message--error to display an Error Message.
• Add a class of spark-message--info to display an Info Message.

Page-Level

Success

<div class="spark-message spark-message--lg spark-message--success spark-panel">
  <div class="spark-panel__content">
    <i aria-hidden="true" class="spark-message__icon spark-icon-check spark-icon--fill"></i>
    <div class="spark-message__content">
      <h4 class="spark-message__heading">
        Success-style message title
      </h4>
      <p>
        Some message to explain in further detail.
      </p>
    </div>
  </div>
</div>

<style type="text/css">
  
</style>

Warning

<div class="spark-message spark-message--lg spark-message--warning spark-panel">
  <div class="spark-panel__content">
    <i aria-hidden="true" class="spark-message__icon spark-icon-alert-triangle spark-icon--fill"></i>
    <div class="spark-message__content">
      <h4 class="spark-message__heading">
        Warning-style message title
      </h4>
      <p>
        Some message to explain in further detail.
      </p>
    </div>
  </div>
</div>

<style type="text/css">
  
</style>

Error

<div class="spark-message spark-message--lg spark-message--error spark-panel">
  <div class="spark-panel__content">
    <i aria-hidden="true" class="spark-message__icon spark-icon-ban spark-icon--fill"></i>
    <div class="spark-message__content">
      <h4 class="spark-message__heading">
        Error-style message title
      </h4>
      <p>
        Some message to explain in further detail.
      </p>
    </div>
  </div>
</div>

<style type="text/css">
  
</style>

Info

<div class="spark-message spark-message--lg spark-message--info spark-panel">
  <div class="spark-panel__content">
    <i aria-hidden="true" class="spark-message__icon spark-icon-note spark-icon--fill"></i>
    <div class="spark-message__content">
      <h4 class="spark-message__heading">
        Info-style message title
      </h4>
      <p>
        Some message to explain in further detail.
      </p>
    </div>
  </div>
</div>

<style type="text/css">
  
</style>

Container-Level

Success

<div class="spark-message spark-message--success">
  <i aria-hidden="true" class="spark-message__icon spark-icon-check spark-icon--fill"></i>
  <p class="spark-message__content">
    <b>Success-style message title.</b> Some message to explain in further detail.
  </p>
</div>

<style type="text/css">
  
</style>

Warning

<div class="spark-message spark-message--warning">
  <i aria-hidden="true" class="spark-message__icon spark-icon-alert-triangle spark-icon--fill"></i>
  <p class="spark-message__content">
    <b>Warning-style message title.</b> Some message to explain in further detail.
  </p>
</div>

<style type="text/css">
  
</style>

Error

<div class="spark-message spark-message--error">
  <i aria-hidden="true" class="spark-message__icon spark-icon-ban spark-icon--fill"></i>
  <p class="spark-message__content">
    <b>Error-style message title.</b> Some message to explain in further detail.
  </p>
</div>

<style type="text/css">
  
</style>

Info

<div class="spark-message spark-message--info">
  <i aria-hidden="true" class="spark-message__icon spark-icon-note spark-icon--fill"></i>
  <p class="spark-message__content">
    <b>Info-style message title.</b> Some message to explain in further detail.
  </p>
</div>

<style type="text/css">
  
</style>

Field-Level Messages

Field-Level Messages appear within a form element and communicates validation information. See the specific form elements for details about field-level validation:

• Text Input
• Select
• Checkboxes
• Radio Buttons

Accessibility Notes

Decorative Icons in Messages

When using Spark Icons as part of the Messaging component, an aria-hidden attribute should be added to the spark-message__icon element if it is a presentational element and the CSS-generated content should not be announced to users.

Approaches for Handling Messages Types

Depending on the type of message to be displayed and the severity or impact to users, there are different approaches that can be used to create accessible Message components.

Important, and Time-Sensitive Messages

When there is a critical issue that occurs on a page, it is important to convey the issue and possible remedies to the user promptly. With the Messages component, this can be done using the ARIA alert role.

The alert role is a Live Region role that is used to inform assistive technologies of dynamic changes to a page’s content so that these can be announced to users. The reason they are announced is that visual changes to a screen, e.g. dynamically displaying a message, may be missed by users with low or no vision.

When working with the alert role, keep in mind the following:

• It should be used for content added dynamically, not for content that exists on page load. If content is not added dynamically, the role attribute should be added dynamically to trigger the alert.
• It should not be used on a focusable element and should not require users to close it.
• It should only be used sparingly, and for information that requires the user’s immediate attention.
• The role should be added to the HTML node containing an alert message, not the element causing the alert.
• This role immediately interrupts the current flow to announce the alert.

In the case of the Messages component, the alert role can be place on the spark-message element when necessary.

<div role="alert" class="spark-message spark-message--lg spark-message--success spark-panel">
  ...
</div>

Messages with Low Importance

When there is a message that needs to be displayed on a page but it is not critical to the user’s current task, the status role can be used.

Like the alert role, the status role is a Live Region role, and there are additional similarities with the alert role:

• It should be used for content added dynamically, not for content that exists on page load. If content is not added dynamically, the role attribute should be added dynamically to trigger the alert.
• The role should not be used on a focusable element and should not require users to close it.
• The role should be added to the HTML node containing an alert message, not the element causing the alert.

Unlike the alert role however, the status role does not result in an immediate announcement by assistive technologies. Instead, it would be announced when there is a pause in the current flow.

In the case of the Messages component, the status role can be place on the spark-message element when necessary.

<div role="alert" class="spark-message spark-message--lg spark-message--success spark-panel">
  ...
</div>

Grouped Messages

In certain situations, multiple events could occur requiring multiple messages to be displayed to the user.

An example is a situation where multiple form errors are displayed at the top of a page. In this scenario, summarizing the errors into a single Message is a better approach as compared to having each error as an individual message.

<div class="spark-message spark-message--lg spark-message--error spark-panel">
  <div class="spark-panel__content">
    <i aria-hidden="true" class="spark-message__icon spark-icon-ban spark-icon--fill"></i>
    <div class="spark-message__content">
      <h4 class="spark-message__heading">
        Error-style message title
      </h4>

      <ol class="spark-mar-b-0">
        <li class="spark-mar-0">This is the first error.</li>
        <li class="spark-mar-0">This is the second error.</li>
        <li class="spark-mar-0">This is the third error.</li>
      </ol>
    </div>
  </div>
</div>

A second example is one where different message types are grouped in a single container. An example of this is illustrated in our Grouped Page-Level Messages. In this scenario, the following guidelines can help determine how to best manage accessibility, usability and the experience:

• Group messages as shown in the example above when it makes sense to do so. This reduces the number of Message components added to the page. For example, if an Error message type and a Warning message type are to be shown, determine if it makes sense to group both as the Error or Warning types.
• Do not use multiple alert roles on a single page at the same time. This is because assistive technologies may clear the alert queue and only announce the first message.
• Determine if it makes sense to use a combination of alert and status roles for different message types depending on how critical they are. Refer to the documentation above on time-sensitive messages.