Messaging
Messaging components are used to provide important and relevant information to the user, including feedback, contextual information, product updates, and more.
Primer Design System
Site navigation
On this page
On this page
Primer includes six different messaging components:
Message types
Messaging holds differing levels of prominence, which can be used to determine the appropriate component to use. Most messages fall into one of the following categories, from most prominent to least:
System updates: These types of message originate from GitHub and are not user initiated. A global site wide announcement (outage, missing payment details, critical and blocking) or messaging related to user account/permissions should use the Announcement component. System announcements related to a specific product area such as a single sign-on message should use the Banner component. System update type messages cannot be dismissed until the issue is resolved, or may be perminent if they are purely informative.
(image here)
Feedback: Communicates the result of a user action (submitting a form, toggling a setting, etc.) Feedback can be positive, negative, or a warning. Feedback is shown in either a Banner or Inline message. For forms, an inline message is used for individual field validation which may be combined with a banner if multiple fields have errors. Banners are placed at the top of the page or section they are related to, but still within the body content. Inline messages are placed near the action they are related to.
(image here)
Awareness: Communicates information that is relevant to the user but not necessarily related to an action they've taken. This type of message is typically used to provide context or additional information about a feature or product. A Banner using the info state might be used to suggest an action or helpful tip, while a Popover is typically used to announce a new feature.
(image here)
Message states
Messaging components combine state with message type to provide the appropriate level of prominence. To determine which component to use for your message, start by identifying the message state.
Overview
| State | Use case |
|---|---|
Info | Use to highlight important information that has an influence on the current view or offers an action |
Success | Informs about successfully completing action. |
Warning | Warn users of side-effect of an action they are about to take or if something happens they may not know about which results in a specific state |
Critical | Inform user about an error that occurs or an action they are about to perform that results in lost access or content |
Info
Use the info state to highlight messages that help users complete a task or that provide additional context.
Examples:
- upgrade account to access a feature
- notify that a process is in progress
- single sign on or other account related notifications
(image of banner in context) (image of callout in context)
Warning
Use the warning state to inform users of a potential issue, an important upcoming change that may impact their experience or a potentially unexpected consequence of an action.
Examples:
- an account setting will become required soon
- a degraded experience due to connectivity or GitHub availability
- a non-destructive action with side-effects like costs or access changes is about to take place
(image of banner in context) (image of callout in context) (image of announcement in context)
Success
Use the success state to notify users that the results of an action were successful if it is not apparent from other parts of the UI.
Examples:
- saving an account setting if there's no page reload or redirect
- a background process has successfully completed
(image of banner in context) (image of inline message in context)
Critical
Use the critical state to notify users that the results of an action were unsuccessful, or to inform that an action is destructive. This state is typically used for form errors and confirmation dialogs.
Examples:
- form field is invalid upon submitting
- a delete or transfer button
Neutral
Reserve the neutral state for inline system related degraded experiences, or for surfacing account related permission messages.
Examples:
- a row of a data table could not be loaded
- an item in a list could not be loaded
- user does not have permissions to perform an action
See degraded experiences for more information.
Visual treatment
Primer offers five states for messaging components: info, warning, success, unavailable, and critical. Each state has a corresponding icon and color combination to help communicate the message's intent.
Icons sized at 14px and above utilize the outline variant, while smaller icons utilize the filled variant.
Placement and persistance
Message proximity and persistance also contribute to the prominence of a message.
Above global navigation
Announcements displayed above the global navigation are reserved for global, site wide issues that require immediate attention. These messages are not dismissable and should only be used for critical issues that impact the entire site.
Top of body
Inline
In a dialog
Dont want to delete this so just moving it down
System updates: inform the user of errors or necessary updates or changes to the product as it relates to them. Announcement are best suited for this type of messaging. Since annoucements are present on every page, they must only be used for global informations like an error that makes the entire web experience slow or the need to update your authentication method to avoid loosing access to your account.
Annoucements can not be dismissed, so they need to be removed once the cause for the annoucement is removed.
Feedback: communicates something to the user based on an action they've taken or caused Banners, toasts or inline messages are best suited for this type of messaging. When the action was taken before loading a page and the message is present on page load, a banner should be used. If the feedback is caused by an action on the current page, an inline message should be used when possible. If the UI does not allow for inline messaging to be used, a toast can be used. Avoid toasts for critical messages, as there are issues with discoverability for some users.
Sometimes complex feedback is shown in a banner instead of an inline message to group mutliple lines together. A common example is a form error summary.
Highlights: bring attention to a specific section. Banners and callouts are best suited when highlighting information about a feature or form. Banners should be used when highlighting information about important side-effects like incurring costs, permanently deleting content or removing access. Callouts are used when providing additional details about an action.
To decide between banner and callout it is important to analyze if the information is a side-effect or expected as part of the action. For example, when creating a codespace, the action is the codespace being created while the side-effect is the cost. However when upgrading your plan, the costs are an expected part of the purchasing action.
Toasts
Toasts are used to provide relevant feedback to the user, typically after they've taken an action. Primer includes styles for success, warning, error, loading, and default toasts. Some examples include:
- Confirmation that an action was successfully taken
- Communicating that an action is pending
- Notifying the user if an action failed to complete
- Providing general information
Toasts are best used in context of the page they're referring to (rather than a global notification that can appear on any page) and should require minimal user interaction. Toasts are best used to display time-sensitive information. For global notices and messaging, see the flash component.
Toasts should be brief and not bog down the experience with superfluous copy. If multiple toasts appear on the page, they will stack naturally.
Do
Use brief and direct communication
Don’t
Don't use wordy and redundant copy
Accessibility
Toasts are non-modal components and should contain role=log, which implies the element has aria-live="polite". This notifies the user of the toast via Assistance Technologies without having to change focus to the toast. You can read more about role=log at W3: Using role=log to identify sequential information updates.
Toasts are generally informative and should not receive focus when they appear. For that reason, we suggest you avoid using interactive elements in the component (aside from a dismiss action). Keep in mind that, even without an explicit dismiss action, the user can always hit esc to dismiss the toast. For more information on how interactive children affect web accessibility, check out this issue.
Flash alerts
Though flash alerts don't need to be as concise as a typical Toast message, they should still be direct and not exceed two to three sentences. If additional context is needed, provide a link for the user to learn more.
Don't use headings or multiple type sizes in flash alerts, rely on our default paragraph size instead.
Full-width
Flash alerts that affect every page (e.g. a global message) should use the full-width style, which spans the entire page and is intended to sit beneath the top-level navigation. When using a full-width flash alert, be sure to include the container class to append a max-width on the content and avoid long line-lengths, which can be difficult to read.
Do
Use a container class to give the text a max-width
Don’t
Don’t let a single text block span the entire width of the window (non-text elements can still span the entire width, such as left-aligned text and right-aligned buttons)
Interactive elements
Flash alerts can contain links or buttons depending on the type CTA and how much attention it should draw.
They typically do not timeout on their own, but can include a dismiss action for messages that can be closed or hidden.
Popovers
Popovers are used to call attention to a new feature, change to an existing feature, or to provide additional context. Popovers can be helpful for flows that require light onboarding or instruction.
Use sparingly to avoid cognitive overload. Though they can be used for a variety of things, they should be used sparingly to avoid cognitive overload. It's important to consider the context in which the popover appears. Are there other popovers on the page? Does it appear on page load, or require the user to open the popover?
Unlike other messaging components, popovers should never include critical information (such as errors) and should always include a dismiss action.