README.md

Alerts

Alerts communicate critical information relating to the state of the system and the user's work flow.

<script type="module">
  import '@brightspace-ui/core/components/alert/alert.js';
  import '@brightspace-ui/core/components/alert/alert-toast.js';
  import '@brightspace-ui/core/components/button/button.js';

  var alert = document.querySelector('#alert');
  var alertToast = document.querySelector('#alert-toast');
  var button = document.querySelector('#open');

  alert.addEventListener('d2l-alert-close', function() {
    if (!alertToast.open) button.style.display = 'block';
  });
  alertToast.addEventListener('d2l-alert-toast-close', function() {
    if (alert.hasAttribute('hidden')) button.style.display = 'block';
  });

  button.addEventListener('click', () => {
    alert.removeAttribute('hidden');
    alertToast.open = true;
    button.style.display = 'none';
  });
</script>
<style>
  d2l-alert-toast {
    margin-left: 0 !important;
    margin-right: 0 !important;
  }
</style>

<d2l-button id="open" style="align-self:center;display:none;">Show Alerts</d2l-button>
<d2l-alert id="alert" type="default" button-text="Undo" has-close-button>
	Inline Alerts can be placed anywhere in the page content
</d2l-alert>
<d2l-alert-toast id="alert-toast" type="success" open no-auto-close>
	Toast Alerts appear at the botttom of the viewport
</d2l-alert-toast>

Inline Alert [d2l-alert]

Use an inline alert if there is important information a user needs to know while performing a task; the alert remains visible until the user takes action or dismisses it.

Best Practices

• Use an alert to highlight information that requires the user’s action or attention
• Provide a clear call to action if it can help resolve the alert
• Use sentence case for alert text and avoid unnecessary punctuation by not placing periods at the end of single sentences

• Don't display more than one paragraph of text
• Avoid overusing them — the more commonly alerts appear, the less effective they will be
• Don't use them for promotional material or information that is not relevant to the user’s workflow
• Don’t use them for validation errors – instead, use the Form component for a consistent user experience

<script type="module">
	import '@brightspace-ui/core/components/alert/alert.js';
</script>

<d2l-alert type="default" button-text="Undo">
	An inline alert message
</d2l-alert>

Properties

Property	Type	Description
button-text	String	Text that is displayed within the alert's action button. If no text is provided the button is not displayed.
has-close-button	Boolean	Gives the alert a close button that will close the alert when clicked
hidden	Boolean	Whether or not the alert is currently visible
subtext	String	The text that is displayed below the main alert message
type	String, default: 'default'	Type of the alert being displayed. Can be one of default, critical, success, warning.

Events

• d2l-alert-close: dispatched when the alert's close button is clicked
• d2l-alert-button-press: dispatched when the alert's action button is clicked

Toast Alert [d2l-alert-toast]

Use a toast alert to provide feedback about an operation the user has just initiated when the result of that operation may not be apparent or obvious to the user. Toast alerts appear at the bottom of the viewport and disappear after 4 seconds by default.

Best Practices

• Use to convey results of a user's action when the result is not otherwise obvious
• Keep text brief — toasts should rarely spill onto more than one line at any screen size
• Use specific language — “Assignment saved” is more informative than “Successfully saved”

• If possible, avoid displaying multiple toasts — see Multiple Toast Alerts
• Don't allow the close button to be blocked by other elements; users shouldn't have to wait for the toast alert to go away on its own
• Don’t use for instructions or critical information since toast alerts disappear and can be easily missed or ignored — use an Inline Alert instead
• Avoid having two lines with subtext — toasts should be very brief

<script type="module">
  import '@brightspace-ui/core/components/alert/alert-toast.js';
  import '@brightspace-ui/core/components/button/button.js';
</script>
<!-- docs: start hidden content -->
<script type="module">
  var alertToast = document.querySelector('d2l-alert-toast');
  var button = document.querySelector('#open');

  alertToast.addEventListener('d2l-alert-toast-close', function() {
    button.style.display = 'block';
  });

  button.addEventListener('click', () => {
    alertToast.open = true;
    button.style.display = 'none';
  });
</script>
<d2l-button id="open" style="align-self:center;display:none;">Show Alert</d2l-button>
<!-- docs: end hidden content -->
<d2l-alert-toast type="default" no-auto-close open>
  A default toast alert
</d2l-alert-toast>

Properties

Property	Type	Description
button-text	optional, String	text that is displayed within the alert's action button. If no text is provided the button is not displayed.
hide-close-button	Boolean, default: false	hide the close button to prevent users from manually closing the alert.
no-auto-close	Boolean, default: false	prevents the alert from automatically closing 4 seconds after opening.
no-padding	Boolean	used to opt out of default padding/whitespace around the alert
open	Boolean, default: false	Open or close the toast alert.
subtext	optional, String	The text that is displayed below the main alert message.
type	String, default: 'default'	The type of the alert being displayed. Can be one of default, critical, success , warning

Events

• d2l-alert-toast-close: dispatched when the toast is closed

Multiple Toast Alerts

Avoid displaying more than one toast message at a time unless absolutely necessary, since they disappear after 4 seconds and can be difficult to read for some users. It's often better to use an inline alert so that users have time to discover and read the message.

For cases where multiple toast alerts are unavoidable, new toast messages will appear at the bottom and push older messages upward.

<script type="module">
  import '@brightspace-ui/core/components/alert/alert-toast.js';
  import '@brightspace-ui/core/components/button/button.js';

  for (let i = 1; i <= 3; i++) {
    const buttonSelector = `#open${i}`;
    const toastSelector = `#alert-toast${i}`;
    document.querySelector(buttonSelector).addEventListener('click', () => {
      document.querySelector(toastSelector).open = true;
    });
  }
</script>

<div style="width:100%;">
  <d2l-button id="open1">Show Alert 1</d2l-button>
  <d2l-button id="open2">Show Alert 2</d2l-button>
  <d2l-button id="open3">Show Alert 3</d2l-button>
</div>
<d2l-alert-toast id="alert-toast1" type="success" open no-auto-close>
	First toast alert
</d2l-alert-toast>
<d2l-alert-toast id="alert-toast2" type="default">
	Second toast, with auto-close
</d2l-alert-toast>
<d2l-alert-toast id="alert-toast3" type="critical" no-auto-close>
	Third toast alert
</d2l-alert-toast>

Accessibility

Inline Alerts are meant to draw attention without interrupting the user's flow, so they do not use the ARIA alert role. This means screen reader users do not hear them until encountering them in the content (as intended).

Toast Alerts leverage the ARIA alert role in alignment with the W3C Alert Pattern, so an assertive live region is created which causes the content of the alert to be announced immediately. This can interrupt the user, so it should be used sparingly as per our Best Practices.