Alert

Examples

View in Pajamas UI Kit →

Structure

1. Container: Wraps the content.
2. Icon: Supports the variant meaning.
   • error icon for error and danger alerts.
   • warning icon for the warning alert.
   • check-circle icon for the success alert.
   • information-o icon for the information alert.
   • bulb icon for the tip alert.
3. Title (optional): Conveys what event triggered the alert.
4. Dismissal (optional): Permanently removes the alert for a user.
5. Message: Text content indicating the purpose and potential next steps.
6. Actions (optional): Buttons used to provide explicit action(s) the user can take to either remedy the alert or continue with a task.

Guidelines

When to use

• Advise a user about a system-generated event or condition related to their current context needing attention.
• Reaffirm to a user that a prior action has been successful. Typically background or async actions initiated in a different location or context.
• Present a dynamic status update based on system conditions or user actions.
• In combination with form validation to help users remedy errors. See the accessibility section for more.

When not to use

• If you need to deliver an instance level message from an admin to all users, use a broadcast message instead.
• If you are immediately confirming a user's action while they remain in the same view, use a toast instead.
• If you are promoting, soliciting feedback, or informing a user about a feature, use a banner instead.
• If you need to display static documentation, warnings, or contextual information that's always present, use contextual help and info patterns instead. These can be styled using feedback and status utility classes. Alerts include focus management and semantic ARIA roles that are intended for dynamic notifications, not static content.

Variants

• Danger: Advise the user that their attention is needed to address or be aware of a critical issue that relates to the current context.
• Warning: Caution the user that their attention or action may be needed within the current context, but it may not be critical.
• Success: Reaffirm to the user that a prior action they have taken, often in a different location within the application, has been successful.
• Information: Provide supplemental information to the user in regards to the current context or action they are about to take.
• Tip: Educate the user about new or unused features, and other useful information.

Behavior

• Permanently dismissible only when the alert relates to a user's individual instance and wasn't triggered by a system condition.
• Permanently dismissible when a task isn't blocked or if no action is required.
• A dismissed alert can reappear if an action or system event reproduces it.

Content

• All copy within an alert should be short, actionable, and use clear language.
• Keep translations in mind when writing copy and follow UI text guidelines.

Title

• Be brief and keep it to a single line by using a sentence fragment.
• Avoid punctuation, like periods, commas, or semicolons.

Message

• Provide next steps, troubleshooting actions, or links to learn about or remedy the event that triggered the alert.
• Avoid paraphrasing the title if one is included.
• Write as if the title was the first sentence of the message.
• Keep to one or two sentences when possible.
• Use sentence case and appropriate punctuation based on our punctuation guidelines.

Actions

• Up to two actions can be used at a time.
• Primary action uses the confirm button variant.
• Secondary action uses the default button variant.
• Left aligned, except in right-to-left languages where they are right aligned and the order is the same. See button alignment and order for more details.

Placement

• Global: Impacts the entire experience, is always full-width, and is placed directly below the breadcrumb bar.

  

• Page-level: Appears near the top of a page, directly above a header section, and is restricted to the content container width, which can be either fixed or fluid, depending on a user’s preference.

  

• In-page: Within a section of the page when the message is specific to that content.

  

Sticky positioning

• Uses position: sticky to keep critical information in view as the page scrolls.
• Helpful when an alert is added without a page refresh and its position would otherwise be out of view.
• Usually is reserved for errors, as they need to be addressed by users.
• Only one sticky alert should be used at a time.

Multiple alerts

• Multiple alerts should be avoided if at all possible, but if necessary ensure the placement of each is in the same context as the content it relates to.
• When multiple alerts are present in the same location, order them from most to least severe.

Accessibility

• An alert should receive focus and use aria-live to announce its presence and allow a user to interact with it immediately.
• If sticky positioning is used, the user must still be able to access and view focusable elements the alert may be covering.
• An alert is separate from, but complimentary to validation error messages. In this way an alert announces that there are validation errors and links a user to each instance.