Alert

An .alert is a message that stays in the page, next to the content it is about, until the problem goes away or the user dismisses it.

Put an optional leading icon in the alert, then the message: a heading, a <p>, or both. Use a snackbar for brief feedback after an action, and a dialog when the user must decide before going on.

<div class="alert">
  <span class="material-symbols" aria-hidden="true">info</span>
  <p>Your trial ends in 3 days. <a href="/plans">See plans</a></p>
</div>

Critical

Add critical for problems that stop something from working. It uses the error container colors.

<div class="alert critical">
  <span class="material-symbols" aria-hidden="true">error</span>
  <h3>Payment failed</h3>
  <p>Your card was declined. Update it to keep your workspace active.</p>
</div>

Actions and close

Put buttons in an .alert-actions row to place them under the message, aligned to the end. Make an .icon-button the last child to use it as the close button. It stays beside the first line. Your page closes the alert. Remove the alert, then move focus to something nearby so focus does not fall back to the top of the page.

<div class="alert">
  <span class="material-symbols" aria-hidden="true">cloud_off</span>
  <p>You're offline. Edits are saved on this device and sync when the connection returns.</p>
  <div class="alert-actions">
    <button class="button text" type="button">Retry sync</button>
  </div>
  <button class="icon-button" type="button" aria-label="Dismiss">
    <span class="material-symbols" aria-hidden="true">close</span>
  </button>
</div>

Announcing changes

An alert that is in the page when it loads needs no role. When an alert appears or changes while the page is in use, put role="status" on its text. Use role="alert" instead when the user must act now. Add the live element to the page before you write the text into it. Keep the buttons out of the live element, because a screen reader would read their labels as part of the message. Never use role="banner", which marks the page header.

<div class="alert critical">
  <span class="material-symbols" aria-hidden="true">error</span>
  <p role="alert" id="save-error"></p>
  <div class="alert-actions">
    <button class="button text" type="button">Try again</button>
  </div>
</div>

Error summary

Put an .error-summary alert at the top of a novalidate form to list what is wrong when the form is submitted. When the user submits while any field is invalid:

1. The submit stops, as it would natively.
2. The Forms behavior writes one link per invalid field into the summary's <ul>, with the field's label and the browser's message. A radio group gets one link, named by its legend.
3. The summary shows and takes focus, so a screen reader reads it.

Each link focuses its field. A valid submit hides the summary again. A submit button with formnovalidate skips the check.

novalidate is required. Without it, the browser stops an invalid form before the submit event, and only the first field's bubble appears. Keep each field's own error text too, because the summary only gathers them.

<form novalidate>
  <div class="alert critical error-summary" hidden aria-labelledby="problem">
    <span class="material-symbols" aria-hidden="true">error</span>
    <h2 id="problem">There is a problem</h2>
    <ul></ul>
  </div>
  <label for="email">Email address</label>
  <input id="email" type="email" required>
  <button type="submit">Send</button>
</form>

Tokens

Override these on the .alert.