Message Banner Component

On This Page

Function

a!messageBanner( primaryText, secondaryText, backgroundColor, highlightColor, icon, showDecorativeBar, shape, marginAbove, marginBelow, showWhen, announceBehavior, accessibilityText )

Displays a message banner that screen readers can announce whenever the component is evaluated. The banner can include primary text, secondary text, accessibility text, an icon, and custom colors. See SAIL Design System: Accessibility for more information about accessibility considerations for the message banner.

This component is best used for information that would be considered a status message per the Web Content Accessibility Guidelines (WCAG). If the content wouldn't be considered a status message, use "DISPLAY_ONLY" for the announceBehavior parameter.

Tip: If you want to provide links or buttons in your message, consider using one of the action banner patterns.

Parameters

Name	Keyword	Types	Description
Primary Text	primaryText	Text	Text to display on the first line inside the banner.
Secondary Text	secondaryText	Text	Text to display beneath the primary text inside the banner.
Background Color	backgroundColor	Text	Determines the background color of the message banner. Valid values: Any valid hex color or hex color including transparency, or `"INFO"` (default), `"SUCCESS"`, `"WARN"`, `"ERROR"`. To add transparency to the hex color, add two additional digits between `00` (more transparent) and `FF` (less transparent).
Highlight Color	highlightColor	Text	Determines the color of the decorative bar and icon. Valid values: Any valid hex color or `"INFO"` (default), `"POSITIVE"`, `"WARN"`, `"NEGATIVE"`.
Icon	icon	Text	Icon to display inside the banner before the primary text. By default, this parameter is null. The icon is intended to be decorative and will not be read by screen readers. See Appian Icons for available icons.
Show Decorative Bar	showDecorativeBar	Boolean	Determines whether a decorative bar is displayed on the banner. Default: `true`.
Shape	shape	Text	Determines the banner shape. Valid values: `"SQUARED"` (default), `"SEMI_ROUNDED"`, `"ROUNDED"` .
Margin Above	marginAbove	Text	Determines how much space is added above the banner. Valid values: `"NONE"` (default), `"EVEN_LESS"`, `"LESS"`, `"STANDARD"`, `"MORE"`, `"EVEN_MORE"`.
Margin Below	marginBelow	Text	Determines how much space is added below the banner. Valid values: `"NONE"`, `"EVEN_LESS"`, `"LESS"`, `"STANDARD"` (default), `"MORE"`, `"EVEN_MORE"`.
Show When	showWhen	Boolean	Determines whether the component is evaluated. When set to false, the banner is not announced and not evaluated. To hide the banner but allow screen readers to read the banner text, set showWhen to `true` and announceBehavior to `"ANNOUNCE_ONLY"`. Default: `true`.
Announce Behavior	announceBehavior	Text	Determines the screen reader behavior for announcing the banner text. Valid values: `"DISPLAY_ONLY"` (default) Banner displays; banner text is not read aloud when the component is evaluated. `"DISPLAY_AND_ANNOUNCE"` Banner displays; banner text is read aloud when the component is evaluated. `"ANNOUNCE_ONLY"` Banner doesn't display; banner text is read aloud when the component is evaluated. In Appian Mobile, `"DISPLAY_ONLY"` is used.
Accessibility Text	accessibilityText	Text	Additional text to be announced by screen readers. Used only for accessibility; produces no visible change.

Usage considerations

Using the announceBehavior parameter

Use the announceBehavior parameter to control how assistive technologies, like screen readers, announce the message banner's text.

The following table explains each option and when to use it.

Option	Behavior	Use When	Example
`"DISPLAY_AND_ANNOUNCE"`	Shows the banner and announces the message when the component is evaluated.	To display a banner for status messages that convey important and timely information regarding a change in page content.	A success message that confirms that a form was submitted.
`"DISPLAY_ONLY"`	Shows the banner but does not announce the message when it appears. The message is only announced if a user navigates to it.	For information that is static and doesn't appear based on a change in the interface.	A banner at the top of a form that provides instructions.
`"ANNOUNCE_ONLY"`	Hides the banner but announces the message when the component is evaluated.	To announce a visual change that a screen reader user would otherwise miss, or to pair an announcement with your own custom-built banner.	Adding or deleting a row in a grid.

Avoid overusing announcements

The "DISPLAY_AND_ANNOUNCE" and "ANNOUNCE_ONLY" options create a "live region" that instructs screen readers to politely announce updates without interrupting the user's current task or shifting the user's focus. Because these live announcements can be disruptive if overused, you should reserve them for important and dynamic changes that are essential for the user to understand what's happening on the interface. For any static or non-critical messages, use "DISPLAY_ONLY".

Color and icon combinations

The following are the predefined backgroundColor, highlightColor, and icon parameter values that are intended to be used together for info, success, error, and warn banners.

Tip: In design mode, you can easily configure info, success, error, and warn banners by selecting Choose a predefined style for Style.

Banner type	Background Color	Highlight Color	Icon
Info	"INFO"	"INFO"	"info-circle"
Success	"SUCCESS"	"POSITIVE"	"check-circle"
Error	"ERROR"	"NEGATIVE"	"exclamation-circle"
Warn	"WARN"	"WARN"	"exclamation-triangle"

Appian Mobile considerations

In Appian Mobile, "DISPLAY_ONLY" is always used for announceBehavior.

Examples

Display and announce a success message

This example shows a message banner that will appear and be announced after a user adds items to their cart.

Use the interactive editor below to test out the example code.

a!localVariables(
  local!selectedSize: "S",
  local!quantity: 1,
  local!quantityAnnounce,
  local!cartCount: 0,
  local!showConfirmation: false(),
  a!headerContentLayout(
    header: a!cardLayout(
      contents: {
        a!sideBySideLayout(
          items: {
            a!sideBySideItem(
              item: a!headingField(
                text: "The Classic Shop",
                fontWeight: "BOLD",
                marginBelow: "NONE"
              ),
              width: "MINIMIZE"
            ),
            a!sideBySideItem(),
            a!sideBySideItem(
              item: a!richTextDisplayField(
                labelPosition: "COLLAPSED",
                value: {
                  a!richTextIcon(
                    icon: "shopping-cart",
                    size: "MEDIUM_PLUS"
                  )
                },
                marginBelow: "NONE"
              ),
              width: "MINIMIZE"
            ),
            a!sideBySideItem(
              item: a!stampField(
                labelPosition: "COLLAPSED",
                text: local!cartCount,
                backgroundColor: "NEGATIVE",
                size: "TINY",
                showWhen: local!cartCount > 0,
                marginBelow: "NONE"
              ),
              width: "MINIMIZE"
            )
          },
          alignVertical: "MIDDLE"
        )
      },
      padding: "STANDARD",
      showBorder: false,
      showShadow: true
    ),
    contents: {
      a!columnsLayout(
        columns: {
          a!columnLayout(),
          a!columnLayout(
            contents: {
              a!cardLayout(
                contents: {
                  a!columnsLayout(
                    columns: {
                      a!columnLayout(
                        contents: {
                          a!imageField(
                            labelPosition: "COLLAPSED",
                            images: {
                              a!webImage(
                                source: "https://images.unsplash.com/photo-1521572163474-6864f9cf17ab?q=80&w=1760&auto=format&fit=crop&ixlib=rb-4.1.0&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D",
                                altText: "Men's Classic Crewneck Tee in white"
                              )
                            },
                            size: "FIT"
                          ),
                          
                        },
                        width: "1X"
                      ),
                      a!columnLayout(
                        contents: {
                          a!headingField(
                            text: "Classic Crewneck Tee",
                            size: "LARGE",
                            fontWeight: "BOLD"
                          ),
                          a!headingField(
                            text: "$25.00",
                            fontWeight: "BOLD"
                          ),
                          a!richTextDisplayField(
                            label: "Description",
                            value: {
                              a!richTextItem(
                                text: "Experience timeless style with our Classic Crewneck Tee. Made from 100% premium, ultra-soft cotton, this t-shirt offers both comfort and durability. It's the perfect foundational piece for any wardrobe.",
                                color: "SECONDARY"
                              )
                            },
                            marginAbove: "STANDARD"
                          ),
                          a!radioButtonField(
                            choiceLabels: { "XS", "S", "M", "L", "XL", "2XL" },
                            choiceValues: { "XS", "S", "M", "L", "XL", "2XL" },
                            label: "Size",
                            value: local!selectedSize,
                            saveInto: local!selectedSize,
                            choiceLayout: "COMPACT",
                            choiceStyle: "CARDS",
                            marginAbove: "STANDARD",
                            marginBelow: "MORE"
                          ),
                          a!headingField(
                            text: "Quantity",
                            size: "EXTRA_SMALL",
                            fontWeight: "BOLD"
                          ),
                          a!sideBySideLayout(
                            items: {
                              a!sideBySideItem(
                                item: a!buttonArrayLayout(
                                  buttons: a!buttonWidget(
                                    icon: "minus",
                                    saveInto: a!save(
                                      local!quantity,
                                      if(
                                        local!quantity > 1, 
                                        local!quantity - 1, 
                                        1
                                      )
                                    ),
                                    size: "SMALL",
                                    style: "OUTLINE"
                                  ),
                                  marginBelow: "NONE"
                                ),
                                width: "MINIMIZE"
                              ),
                              a!sideBySideItem(
                                item: a!integerField(
                                  labelPosition: "COLLAPSED",
                                  value: local!quantity,
                                  saveInto: local!quantity
                                ),
                                width: "1X"
                              ),
                              a!sideBySideItem(
                                item: a!buttonArrayLayout(
                                  buttons: a!buttonWidget(
                                    icon: "plus",
                                    saveInto: a!save(
                                      local!quantity, 
                                      local!quantity + 1
                                    ),
                                    size: "SMALL",
                                    style: "OUTLINE"
                                  ),
                                  marginBelow: "NONE"
                                ),
                                width: "MINIMIZE"
                              ),
                              a!sideBySideItem(width: "4X")
                            },
                            alignVertical: "MIDDLE"
                          ),
                          a!buttonArrayLayout(
                            buttons: {
                              a!buttonWidget(
                                label: "Add to Cart",
                                icon: "shopping-cart",
                                saveInto: {
                                  a!save(
                                    local!cartCount,
                                    local!cartCount + local!quantity
                                  ),
                                  a!save(
                                    local!showConfirmation, 
                                    true
                                  ),
                                  a!save(
                                    local!quantityAnnounce, 
                                    local!quantity
                                  )
                                },
                                width: "FILL",
                                style: "SOLID",
                                color: "#111827",
                                loadingIndicator: true
                              )
                            },
                            marginAbove: "STANDARD"
                          ),
                          a!messageBanner(
                            primaryText: local!quantityAnnounce & char(32) & "item(s) added to your cart",
                            backgroundColor: "SUCCESS",
                            highlightColor: "POSITIVE",
                            icon: "check-circle",
                            showWhen: local!showConfirmation,
                            accessibilityText: local!cartCount & char(32) & "total items in your cart"
                          )
                        },
                        width: "1X"
                      )
                    },
                    spacing: "SPARSE"
                  )
                },
                shape: "ROUNDED",
                padding: "MORE",
                marginAbove: "MORE",
                marginBelow: "MORE",
                showShadow: true
              )
            },
            width: "WIDE_PLUS"
          ),
          a!columnLayout()
        }
      )
    },
    backgroundColor: "#F3F4F6"
  )
)

Announce only when a grid row is added or removed

In this scenario, a sighted user can see that a row has been added or removed from the grid. For a non-sighted user, we can use an ANNOUNCE_ONLY message banner to announce that the action was successful without displaying a visible banner.

Use the interactive editor below to test out the example code.

a!localVariables(
  local!gridData: {
    { id: 1, item: "Laptop", description: "Apple MacBook Pro", quantity: 1 },
    { id: 2, item: "Mouse", description: "Apple", quantity: 1 }
  },
  local!itemAdded,
  local!rowAdded, 
  local!itemRemoved, 
  local!rowRemoved, 
  {
    a!gridLayout(
      label: "Order Items", 
      headerCells: {
        a!gridLayoutHeaderCell(
          label: "Name"
        ), 
        a!gridLayoutHeaderCell(
          label: "Description"
        ),
        a!gridLayoutHeaderCell(
          label: "Quantity", 
          align: "RIGHT"
        ), 
        a!gridLayoutHeaderCell(
        )
      },
      columnConfigs: {
        a!gridLayoutColumnConfig(),
        a!gridLayoutColumnConfig(),
        a!gridLayoutColumnConfig(),
        a!gridLayoutColumnConfig(
          width: "ICON"
        )
      },
      rows: {
        a!forEach(
          items: local!gridData, 
          expression:
          a!gridRowLayout(
            contents: {
              a!textField(
                value: fv!item.item, 
                saveInto: fv!item.item
              ), 
              a!textField(
                value: fv!item.description, 
                saveInto: fv!item.description
              ), 
              a!integerField( 
                value: fv!item.quantity, 
                saveInto: fv!item.quantity,
                align: "RIGHT" 
              ), 
              a!buttonArrayLayout(
                buttons: {
                  a!buttonWidget(
                    icon: "times", 
                    tooltip: "Remove item", 
                    saveInto: {
                      a!save(
                        local!gridData,
                        remove(local!gridData, fv!index)
                      ),
                      a!save(
                        local!itemRemoved,
                        true()
                      ), 
                      a!save(
                        local!rowRemoved,
                        fv!index
                      )
                    }, 
                    style: "LINK", 
                    color: "ACCENT"
                  )
                }
              )
            }
          )
        )
      }, 
      addRowLink: a!dynamicLink(
        label: "Add item", 
        saveInto: {
          a!save(
            local!gridData,
            append(local!gridData, {id: length(local!gridData) + 1, item: null(), description: null(), quantity: null()})
          ),
          a!save(
            local!itemAdded,
            true()
          ), 
          a!save(
            local!rowAdded,
            length(local!gridData)
          )
        }
      )
    ),
    a!messageBanner(
      secondaryText: "A new item has been added to the grid (row " & local!rowAdded & ")",
      showWhen: a!isNotNullOrEmpty(local!itemAdded),
      announceBehavior: "ANNOUNCE_ONLY"
    ), 
    a!messageBanner(
      secondaryText: "An item has been removed from the grid (row " & local!rowRemoved & ")",
      showWhen: a!isNotNullOrEmpty(local!itemRemoved),
      announceBehavior: "ANNOUNCE_ONLY"
    )
  }
)

Display only an informational message on page load

This example shows how to use the message banner to display an informational message that is present when the interface first loads. Since the information is not a result of a user action within the interface, DISPLAY_ONLY is the appropriate announce behavior.

Use the interactive editor below to test out the example code.

a!headerContentLayout(
  header: {
    a!cardLayout(
      contents: {
        a!headingField(
          text: "Sales Dashboard",
          size: "MEDIUM_PLUS",
          fontWeight: "BOLD",
          marginAbove: "NONE",
          marginBelow: "NONE"
        )
      },
      height: "AUTO",
      style: "ACCENT",
      padding: "MORE"
    )
  },
  contents: {
    a!messageBanner(
      primaryText: "System Maintenance",
      secondaryText: "The system will be down for maintenance this Saturday from 10 PM to 11 PM.",
      backgroundColor: "INFO",
      highlightColor: "INFO",
      icon: "info-circle",
      announceBehavior: "DISPLAY_ONLY",
      marginBelow: "MORE"
    ),
    a!cardLayout(
      contents: {
        a!richTextDisplayField(
          labelPosition: "COLLAPSED",
          value: {
            a!richTextItem(
              text: {
                "Dashboard content would go here"
              },
              style: {
                "EMPHASIS"
              }
            )
          },
          align: "CENTER"
        )
      },
      height: "TALL",
      style: "TRANSPARENT",
      marginBelow: "STANDARD"
    )
  },
  backgroundColor: "#FBFBFB",
  contentsPadding: "MORE"
)

Feature compatibility

The table below lists this component's compatibility with various features in Appian.

Feature	Compatibility	Note
Portals	Compatible
Offline Interfaces	Compatible
Sync-Time Custom Record Fields	Incompatible
Real-Time Custom Record Fields	Incompatible	Custom record fields that evaluate in real time must be configured using one or more Custom Field functions.
Process Reports	Incompatible	Cannot be used to configure a process report.
Process Events	Incompatible	Cannot be used to configure a process event node, such as a start event or timer event.
Process Autoscaling	Incompatible	Cannot be used in autoscaled processes.
Event Consumer Filter Conditions	Compatible	Can be used in filter conditions.
Event Consumer Event Handlers	Compatible	Can be used in event handler expressions.

The following recipes include usage of the Message Banner Component.

Document List Pattern (Documents):
Use the document list items pattern to display a list of documents that can be searched and filtered. This pattern uses a combination of cards and rich text to show an easy to navigate list of documents of different types.

Feedback

Was this page helpful?

Message Banner Component

Function

Parameters

Usage considerations

Using the announceBehavior parameter

Avoid overusing announcements

Color and icon combinations

Appian Mobile considerations

Examples

Display and announce a success message

Announce only when a grid row is added or removed

Display only an informational message on page load

Feature compatibility

Related recipes

Feedback