This is Cedar’s legacy site. Information may be outdated.
Go to Cedar's new documentation site for the latest features and support.

Banner

Provides contextual feedback messages for typical user actions

# Overview

A banner is used to communicate a general status event or to promote a feature.

CdrBanner is a simple wrapper component that allows for composing various banner layouts. There are five different options for styling the banner, based on the banner type.

# Default Banner with Icon Left

Banners should be passed an appropriate icon and text for the banner message type.

# Message Body

CdrBanner provides an optional message-body slot in the case where additional information about the message needs to be communicated.

# Icon Right

CdrBanner provides an optional icon-right slot that can be used to provide an action related to the Banner such as a close button. The actionable element should have an aria-label that explains it's relationship to the banner and what happens when you click on it.

# Info Action

Optional info-action slot that can be used to provide an action related to the Banner such as a link or tooltip. The actionable element should have an aria-label that explains it's relationship to the banner and what happens when you click on it.

# Accessibility

Many WCAG requirements are contextual to their implementation. To ensure that usage of this component complies with accessibility guidelines you are responsible for the following:

  • Add role="alert" for messages that are important or time sensitive to ensure that the messaging is immediately announced to screen readers. For other content, add aria-live="polite".
  • For static messaging that calls out the type of banner in the text and that is loaded with the page there is no need to do anything specific
  • For messages that do not include text to identify what type of banner is being displayed users should add screen reader only text that adds this information to the start of their message
  • Don't rely on color alone to convey your message. Provide an additional indicator to color, like an icon: WCAG 1.4.1 (opens new window)
  • Error Identification techniques and criteria: WCAG 3.3.1 (opens new window)

# Guidelines

Banner messaging keeps users informed of important and sometimes time-sensitive changes contextual to inline elements on the page. These messages help to clarify an issue and/or notify users of a potential problem that may require their attention.

There are five information types supported for banners: error, warning, success, informational, and default. Each type corresponds with a color and icon to provide a consistent, universal experience for users.

# Information types

# Error

Use to inform that something went wrong. They affect or block the user's experience and must be resolved before moving forward.

# Warning

Use for a message requiring attention but not resolution in order to continue. Warning banners might tell a user what could happen if they don’t address what they’re being warned about.

# Success

Use to communicate that an action has been successfully completed. Provides a positive response to user actions. No action is required.

# Informational

Use to provide context around a situation. No action is required.

# Default

Use to provide generic messaging that does not fit the other types.

# Use when

  • When communicating an event not related to a specific task
  • When promoting a new feature
  • Indicating that a change has happened since a previous session
  • Read more about using Banners for Status Notifications

# Don't use when

  • When validation is required immediately after the user interacts with a form input. Instead, use the built-in validation features of form components

# Content

  • An icon is both user-configurable and required
  • Body copy should not exceed two lines
  • Content should be focused and be specific to a single message
  • A call-to-action may be included

# Structure

  • A banner always spans the width of its parent container
  • The height of a banner is variable, content depending

# Behavior

  • A banner persists until their conditions are either met or they are dismissed
  • Banners with the role of alert are not dismissible

# Placement

  • Banners should be placed above their area of concern
  • Banners that persist across pages should sit alongside the global header

# API

View it on Github: https://github.com/rei/rei-cedar-vue-2/tree/next/src/components/banner

# Props

type

name

string

type

'default'

default

Sets the banner style. Possible values: { 'info' | 'success' | 'warning' | 'error' | 'default'}

# Slots

Find more information about using Slots in the article Installing Cedar.

default

name

Slot for primary message text

icon-left

name

Slot for icon matching banner type

message-body

name

Slot for additional content about the message

icon-right

name

Slot for an additional icon on right

info-action

name

Slot for an action-wrapped icon