Notification 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 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 messages originate from GitHub and are not user initiated. 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 permanent if they are purely informative. Global system announcements that are relevant beyond the current page use an Announcement (not a Primer component).
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.
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, while an InlineMessage might suggest a helpful tip.
See the message type flowchart to help determine the appropriate message type for specific use cases.
Message states
Visual treatment
Primer offers six states for messaging components: info, warning, success, unavailable, critical, and upsell. Each state has a corresponding icon and color combination to help communicate the message's intent.
Icons sized at 12px utilize the filled variant, while 16px and 24px utilize the outline variant paired with 14px text or larger.
Overview
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.
| State | Use case |
|---|---|
Info | Highlights important information that has an influence on the current view or offers an action. |
Warning | Informs about a potential issue or consequence as the result of an action. |
Critical | Informs about an error that occured or warns about loss of access or data as a result of an action. |
Success | Informs about successfully completing an action. |
Unavailable | Informs about degraded experiences or outages. |
Upsell | Highlights features that are available for specific account types such as Enterprise. |
Info
Use the info state to highlight messages that help users complete a task or that provide additional context.
Examples:
- Single sign on or other account related notifications
- General information about a feature or setting
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
Critical
Use the critical state to notify users that an action was unsuccessful, to display form errors, or to inform that an action is destructive.
Examples:
- Form field is invalid upon submitting
- A delete or transfer button
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. Use success messaging sparingly and rely more on interaction context.
Examples where a success message is needed:
- Copy button, the copy to clipboard action was successful.
After clicking the copy icon button, a green checkmark appears to the right of the icon button.
- Creating multiple new issues.
After clicking the Create button, an inline message appears below the Create button that says, Issue #21 created, with Issue #21 being a link.
Examples where a success message is not needed:
- Saving the comment edit or title edit of an Issue, where the success is indicated by the return to the updated comment or title in non-edit mode.
- Creating a single new issue, where a user is brought to the newly created issue page upon successful creation.
Unavailable
Reserve the unavailable 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.
Upsell
Use the upsell state to highlight features that could be unlocked if the user upgrades their account.
Examples:
- Upgrade account to access a feature
Placement
Message proximity contributes to the prominence of a message. Whenever possible, place messages near the action they are related to.
Top of body
If messaging pertains to an entire page or section, place it at the top of the body content. This is the most common placement for messaging components. Banners should fill the container width but maintain appropriate spacing between elements and not appear full width or flush under the global nav.
Inline
Inline messages are used to provide feedback on a specific action or input field. They should be placed near the action they are related to.
Inside a dialog
Banners should be placed below the Dialog header and appear full width within the Dialog content area. Prioritize showing messaging inside the Dialog after an action rather than closing the Dialog and showing a banner within the page.
Placement recommendations
Do
Place banners in close proximity to where the interaction occured.
Don’t
Don't place banners related to internal dialog content at the top of a page.
Do
Use InlineMessage when immediate feedback is needed as the result of an action.
Don’t
Don’t place messaging far from the user action when space is available.
Choosing a message type
Picking a notification message for an experience can be tricky. Reference this flowchart to help pick the best component for your feature. For more nuanced scenarios, reach out to the Primer team for recommendations.