An alert is a system generated, contextual, and timely message to a user that may or may not result from their action.


Loading story...

View in Pajamas UI Kit →


Numbered diagram of an alert structure
Alert structure
  1. Container: Wraps the content.
  2. Icon: Supports the variant meaning.
  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.


When to use

  • Advise the user that they should be aware of, or address something related to their current context.
  • Reaffirm to the user that a prior action, likely in a different location or context, has been successful.
  • Educate the user about new or unused feature, or information related to their current context.
  • 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.


  • 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.


  • 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.


  • 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.


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


  • 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.


  • 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.


  • Global: Impacts the entire experience, is always full-width, and is placed directly below the breadcrumb bar.
    Global alert position
    Full-width danger alert
  • 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.
    Page-level alert position
    Page-level danger alert in the main content area with space above and below
  • In-page: Within a section of the page when the message is specific to that content.
    In-page alert position
    In-page danger alert contextually placed with space above and below

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.


  • 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.

Last updated at: