Components

Message

Message framework that can include text, images, and actions for use cases such as empty states and confirmation messages

Overview

  • Available since: Quebec
  • A11Y: WCAG 2.1 AA

Message is a component to communicate important information that require user attention, such as success messages, warnings, or errors. This can include text, images, and actions.

ServiceNow link
Message code documentation

UIB and developer guidance

Figma link
Message Figma component

Horizon components and styles library

Loading playground

When to use

Use message when you need to provide feedback or alert users about specific actions, success states, errors, or other important information such as empty states and confirmation messages.

When not to use

Don’t use message for unnecessary information that may disrupt the user’s workflow. Overuse of this component can lead to user frustration and diminish the impact of important information.

Anatomy

anatomy of message component
  1. Media (optional): An illustration, icon, image, or video that adds context to the message
  2. Content slot (optional): Text that conveys the topic and purpose of the message
  3. Actions (optional): Types of buttons or actions

Subcomponents

See usage guidance for button

Usage

You can use the message component for an empty state, feedback, or confirmation.

Empty state

You can use a message in an empty state to explain the current situation and offer actions for next steps.

empty state message and illustration with astronaut and magnifying glass

In this example, the content slot offers recommendations on how to see results.

Feedback

You can include a message when you want to get feedback from the user. These messages include positive and negative actions for the user to choose.

boolean feedback message with positive and negative action buttons

Confirmation

You can use a message as confirmation for a user-initiated action.

confirmation message with check icon and action button

In this example, the message confirms that the user's account is now verified.

Variants

The order of the elements within message type is predefined and can't be changed.

Configurations

Learn how to customize message by configuring the available properties.

Alignment and positioning

The message component has different alignments for the media, content slot, and actions. Your individual use case determines the positioning for the parts of the message.

Vertical

Use the vertical alignment to display content in limited horizontal spaces.

message component in vertical alignment

Vertical centered

You can also use the vertical centered alignment in limited horizontal spaces, too.

message component in vertical centered alignment

Horizontal

Use the horizontal alignment to display content in limited vertical spaces. Text and actions adjust to left alignment or optional content may be omitted. Buttons in the action slot display side-by-side. Horizontal is the default alignment.

message component in horizontal alignment

Design recommendations

Learn how to apply message in your design.

proper display of primary and secondary buttons
Do

Use only 1 primary action in a message to show the most important or common action.

improper display of 2 primary buttons
Don’t

Avoid making a user choose between 2 primary actions.

proper display of 2 positive and negative action icons for user feedback
Do

Make sure icons clearly distinguish positive and negative actions.

improper display of 2 positive icons with positive and negative action buttons for user feedback
Don’t

Avoid confusing users by displaying 2 positive icons.

button text with distinct options presented
Do

Choose distinct button wording so users can easily distinguish between the choices.

button text with lengthy wording to avoid
Don’t

Avoid lengthy wording that's not easily recognizable as a button label.

proper display of another component within the message component
Do

Only add another component in the content slot if it provides more context and actions.

improper display of another component within the message component
Don’t

Avoid adding another component in the content slot if it doesn't suit the use case or might confuse the user.

UI text guidelines

These are some recommendations for using text within message:

  • If using the content slot, provide the person with a message that tells them more about why this message appeared.
  • If using header and body text in the content slot, make sure the text in each is unique to avoid repetition. Use the header to tell them what happened, then use the body text to provide any additional information, context, or next steps.
    • For example, the header could be, “Message submitted” and the body text could be, “We’ll notify the recipient via email.”
  • If using buttons in the message, they should be the next suggested actions the person should take. You can also offer independent choices instead of verbs to help the person respond to the message.
    • For example, if the message is asking the user if they would like to provide feedback, the buttons could be “Yes” and “No”.

Behavior

Learn how message behaves when the display changes or a user interacts with the component.

States

Message doesn't have any states. Only the buttons have individual states. The buttons use the same interaction and behavior as the button component.

See usage guidance for button

Responsive behaviors

If the message uses a horizontal alignment, it changes to a vertical alignment as the display gets smaller.

vertical alignment adapted to minimum width

Interactions

The user can select the button(s), if available, to take an action on the message. You can configure the type of action the button performs. For example, you could direct the user to a different page or collect their feedback on a particular question.

Truncation

Message text doesn't truncate. Text in the content slot wraps to the next line as needed without truncation.

message with wrapping behavior

Usability

Message complies with all internationalization and accessibility requirements.

Internationalization

When the display translates to a right-to-left (RTL) language, the content flips and aligns on the opposite side, and the primary button appears on the left instead of the right. Only icons that indicate direction will flip.

content slot and action slot positions for right-to-left languages

If you want to include an icon with the button labels, consider how other cultures may interpret the icon in a positive or negative way.

Accessibility

Learn how to access the actionable elements of message through keyboard interactions and screen readers.

Keyboard interactions

You can access the actionable elements of message with these keyboard keys:

  • Tab: Moves focus to the button
  • Space or Enter: Initiates the button when it has focus

Screen readers

When you apply ARIA labels to a component, screen readers announce the controls and content of message in the prescribed tab order.

  • Screen readers announce the content slot and button, so users can understand a button function
  • For buttons with icons and without text, apply aria-label to explain intent of the button