Skip to content

Messaging

Messaging components are used to provide important and relevant information to the user, including feedback, contextual information, product updates, and more.

Primer includes three different messaging components:

Messaging types

It's important to consider the context when selecting a component to convey your message. Does the message need to interrupt the user flow? Is this a global message that needs to be shown on every page? Does it require the user to take an action, or is it more of a notice? Most messaging on GitHub falls into one of the following categories:

Feedback: communicates something to the user based on an action they've taken or a change in context

  • Toasts or flash alerts are best suited for this type of messaging.

Highlights: bring attention to how and why to engage with a feature

  • Popovers are best suited for this type of messaging.

Updates: inform the user of necessary updates or changes to the product as it relates to them.

  • Flash alerts are best suited for this type of messaging.

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

Flash alerts are used to display updates or alerts pertaining to any part of the system; this includes information regarding the user's account, the organization, the repo, and more. These updates are typically not user-initiated but rather alerts that require the user's attention. Similarly to toasts, flash alerts can convey a warning, error, success, or a neutral message.

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.

Edit this page on GitHub
9 contributorskhiga8josepmartinswbrijeshyailimayakaczcolebemisBinaryMuseemilybrickampinsk
Last edited by khiga8 on December 22, 2022