Garden 9 is now available.
The website has been updated to the latest major version. View previous versions
Skip to main content
Design
Components
Patterns
    • Introduction
      • Overview
    • Patterns
      • Buttons
      • Copy
      • Drag and drop
      • Error handling
      • Filters
      • Loaders
      • Rich-text editor
      • Save
      • Tables
    Table of Contents
    • Global Alerts
      • Anatomy
      • Layout
      • Examples
    • Alerts
      • Anatomy
      • Layout
    • Notifications
      • Anatomy
      • Layout
      • Examples
    • Forms
      • Anatomy
      • Layout
      • Formatting
    • Accessibility
      • Additional resources

    Error handling

    Error messages let users know that a problem has occurred and what to do about it.


    Table of Contents
    • Global Alerts
      • Anatomy
      • Layout
      • Examples
    • Alerts
      • Anatomy
      • Layout
    • Notifications
      • Anatomy
      • Layout
      • Examples
    • Forms
      • Anatomy
      • Layout
      • Formatting
    • Accessibility
      • Additional resources

    Examples of errors include:

    • The system has failed to load or perform an action
    • The user has made an incorrect action or input

    Error messages are best surfaced using these components:

    • Global Alerts
    • Alerts
    • Notifications
    • Validation messages

    Global Alerts

    Use the Global Alert to communicate system level errors that interrupt a user’s task.

    Anatomy

    • Always include a title to explain what has went wrong and how to fix it
    • Provide a clear action to address the issue
    Global Alert anatomy
    1. The Title announces what has went wrong
    2. The Content area describes how to address the issue. It may include an anchor to provide additional information
    3. This Button provides a way to resolve the error. This button is placed towards the end of the Global alert

    Layout

    Global Alerts sit above chrome and push all page content down. They are the first item seen and announced by screen readers. For errors, Global Alerts should be persistent until the issue has been resolved by the user or system.

    Global Alert layout

    Examples

    Disconnection

    Use the Global Alert component to communicate that users have lost the connection to Zendesk. Provide a button to allow users to reconnect. There is no close button as the alert should only be dismissed when the connection is restored.

    Global Alert example, user has been disconnected

    Alerts

    Use alerts to communicate contextual information on how to fix an error. They persist until they are dismissed by the user or the issue is resolved. They are most commonly used in conjunction with validation messages in forms.

    Anatomy

    Alert anatomy
    1. Title
    2. The Paragraph area describes in more detail the error and how to fix
    3. The Close button is an icon button, at the end of the Alert

    Layout

    Alerts appear near their related items. They can expand to fill the width of the container or area they are in.

    Alert layout

    In conjunction with forms

    Alert example with form inputs
    1. An Alert at the beginning of the form to summarize what went wrong
    2. Each individual form input with errors is highlighted

    Notifications

    Use error notifications when an activity can not be completed.

    Anatomy

    Notifications anatomy
    1. Title
    2. Message
    3. Close button

    Layout

    Notifications should sit on the top right side of a workspace and remain on screen for at least 5 seconds. Avoid covering important elements.

    Notifications layout

    Examples

    Failed actions

    The notification component helps communicate that an action could not be completed.

    Notification example, File upload has failed
    1. An error notification appears at the top right of the screen indicating that the user’s image could not be uploaded

    Forms

    Use the message component to help users correct input errors as they happen. Clearly explain how to fix the error.

    Anatomy

    Forms anatomy
    1. The input field’s border turns red to indicate an error
    2. Provide a detailed error message to describe what went wrong

    Layout

    Multiple form errors

    For multiple form errors, provide inline error messages for each. Also provide an Alert at the top of the form, listing a summary of the fields that need correcting.

    Forms example, multiple form errors

    Formatting

    Validate on submit

    Use validation messages after submission to reduce interrupting users as they move through forms. Live validation should be used sparingly (i.e. severe errors, passwords, emails).

    Do this
    • Show error validation after the user has tried submitting the form
    Not this
    • Do not use live validation

    Keep data the user has entered

    Keep incorrect values that users have entered to help them avoid making the same mistake twice.

    Do this
    • Keep invalid data to let users understand what to correct
    Not this
    • Do not clear invalid data

    Accessibility

    Error messages need to be perceivable and understandable for people of all abilities. An accessible error message should exhibit these qualities.

    • Written in text. Icons and color can be used, but not alone.
    • Close to the element that triggered the error
    • Informative, helping the user resolve the issue
    • The message should refer to the failed element in code

    Additional resources

    https://www.w3.org/WAI/standards-guidelines/act/rules/36b590/proposed/ https://www.w3.org/WAI/WCAG21/Understanding/error-identification.html https://www.w3.org/WAI/WCAG21/Understanding/error-suggestion.html

    Garden is the design system by Zendesk.
    BlogGitHubVersions
    © Zendesk 2025