Alerts and Errors

Playground

Alert Box

Alert boxes are for alert messages that apply to an entire page, or to a section of a page. For instance, if a user has incorrectly filled out some form fields, each form field might get its own individual error message, but the whole form would also get an Alert Box at the top, right below the form's heading, to call attention to the entire form.

<AlertBox>Saving changes...</AlertBox>

<div class="alert-box" role="alert">Saving changes...</div>

Alerts can contain multiple paragraphs as necessary:

Dismiss Button

With rare exception, an `AlertBox` should be dismissible by the user.

In React: just add an AlertBoxDismissButton inside of the AlertBox. The AlertBoxDismissButton has one required prop, visuallyHiddenLabel, which is a string that describes the dismiss button to screen readers. Don't forget to localize this text!

In vanilla JS: place a button <button class="alert-box-close-button"> inside the Alert Box, at the end of the content. Inside the button, place the localized text of the string that describes the button.

<AlertBox>
  Alert!
  <AlertBoxDismissButton visuallyHiddenLabel="Dismiss alert" />
</AlertBox>

<div class="alert-box alert-box-skinname" role="alert">
  Alert!
  <button class="alert-box-close-button">
    Dismiss alert
    <!-- you must provide localized text for the close button, even though this text will be hidden on screens -->
  </button>
</div>

Narrow

Use the "narrow" option to give it a maximum width, rather than having it fill all available width.

<AlertBox widthVariant="narrow">
  Saving changes...
  <AlertBoxDismissButton visuallyHiddenLabel="Dismiss alert" />
</AlertBox>

<div class="alert-box alert-box-narrow" role="alert">
  Saving changes...
  <button class="alert-box-close-button">
    Dismiss alert
    <!-- you must provide localized text for the close button, even though this text will be hidden on screens -->
  </button>
</div>

Toast

A "toast" is an Alert Box that pops up, typically from the bottom of the screen, like toast out of a toaster. The "toast" option for an Alert Box provides a slightly different visual look.

Note: Visage just provides the styling, and doesn't provide any animation for the Toast automatically. This way, you can tailor the positioning and animation for your application's user experience.

<AlertBox toast>Saving changes...</AlertBox>

<div class="alert-box alert-box-toast" role="alert">Saving changes...</div>

Skins

"error" skin

<AlertBox skin="error">
  Please correct the issues below.
  <AlertBoxDismissButton visuallyHiddenLabel="Dismiss alert" />
</AlertBox>

<div class="alert-box alert-box-error" role="alert">
  Please correct the issues below.
  <button class="alert-box-close-button">Dismiss alert</button>
</div>

"warning" skin

<AlertBox skin="warning">
  The text is outside the canvas and will be cut during printing.
  <AlertBoxDismissButton visuallyHiddenLabel="Dismiss alert" />
</AlertBox>

<div class="alert-box alert-box-warning" role="alert">
  The text is outside the canvas and will be cut during printing.
  <button class="alert-box-close-button">Dismiss alert</button>
</div>

"positive" skin

<AlertBox skin="positive">
  Your design has been saved.
  <AlertBoxDismissButton visuallyHiddenLabel="Dismiss alert" />
</AlertBox>

<div class="alert-box alert-box-positive" role="alert">
  Your design has been saved.
  <button class="alert-box-close-button">Dismiss alert</button>
</div>

"legal warning" skin

This skin is intended for legally-required warning messages, such as those covered by California's Prop 65. These Alert Boxes should not have a close button. This skin has specific legal requirements governing its icon, font size, and font color. These Alert Boxes should not have a close button.

<AlertBox skin="legal-warning">
  <strong>WARNING</strong>: This product can expose you to Diisononyl Phthalate
  (DINP), which is known to the State of California to cause cancer. For more
  information go to{' '}
  <a href="http://www.P65Warnings.ca.gov">www.P65Warnings.ca.gov</a>.
</AlertBox>

<div class="alert-box alert-box-legal-warning" role="alert">
  <strong>WARNING</strong>: This product can expose you to Diisononyl Phthalate
  (DINP), which is known to the State of California to cause cancer. For more
  information go to
  <a href="http://www.P65Warnings.ca.gov">www.P65Warnings.ca.gov</a>.
</div>

Controlled

In React, if you'd like to take control of the dismissed-state, you can provide the dismissed prop.

Provide the onRequestDismiss handler in order to be notified when the AlertBox wants to be dismissed.

() => {
  const [dismissed, setDismissed] = React.useState(false)
  return (
    <AlertBox
      dismissed={dismissed}
      onRequestDismiss={() => {
        setDismissed(true)
        // for demo purposes, we'll un-dismiss the alert after a few seconds
        setTimeout(() => {
          setDismissed(false)
        }, 2000)
      }}
    >
      Alert!
      <AlertBoxDismissButton visuallyHiddenLabel="Dismiss alert" />
    </AlertBox>
  )
}

Guidelines

Developer Guidelines

• When an alert occurs, preserve as much user input as possible, so that the user can modify their (incorrect) information, rather than have to re-enter it from scratch.

Accessibility Guidelines

• Users with vision issues may not be able to see the icon and/or color of the alert. For clarity, the nature of the alert must be clear via text alone. It may be useful to add some of the text visually-hidden to the alert that won't show up on screens. For instance, a positive alert indicating that an operation has succeeded might have the visually hidden text "Success:" at the start of the message.

• You must provide localized text inside the dismiss button saying "Close alert" or "Dismiss alert". This text will be hidden on screens, but will guide users on assistive technologies. In React, use the visuallyHiddenLabel above.

• If you are dynamically adding an alert after initial page load, then the content area where the alert will appear will need to already have role="status" aria-live="polite" on it. These attributes inform assistive technologies that they need to notify the user when any content inside that area changes, and thus the browser will announce the alert when it appears.

Form input errors

Form input errors indicate where a user's input for a specific input field was invalid or incorrect. See more on the Form page.

<StandardForm>
  <FormField>
    <FormLabel>
      Favorite animal <FormLabelOptional>(Optional)</FormLabelOptional>
    </FormLabel>
    <FormInputGroup>
      <TextInput />
      <FormError>This field has an error</FormError>
    </FormInputGroup>
  </FormField>
</StandardForm>

Guidelines

Designer Guidelines

• Form input errors should occur directly below their input, inside an Input Group as part of a Form.

• Use form input errors for errors with individual text fields and dropdowns. If there is an error with a set of radio buttons, use an Alert Box at the top of the radio buttons, rather than put form input errors next to each of the radio buttons.

Developer Guidelines

• When an error message occurs, preserve as much user input as possible, so that the user can modify their (incorrect) information, rather than have to re-enter it from scratch.

Accessibility Guidelines

• When a form input field has a visible error message, the input should have aria-invalid="true" to indicate that its current value is invalid. It should also have both an aria-describedby attribute and an aria-errormessage attribute, both of whose values are the id of the error message.

• If you are dynamically adding an error message after initial page load, then the content area where the error will appear will need to already have role="status" aria-live="polite" on it. These attributes inform assistive technologies that they need to notify the user when any content inside that area changes, and thus the browser will announce the error message when it appears.

Components