Banner

Importing

import { Banner, BannerDescription, BannerTitle } from '@customerio/pluma-components/react';

Elements of a banner

Variant

A banner's variant is tied to its semantic meaning, and determines the color and default icon used in a banner. The available variants are:

• default
  • Used to share non-urgent information such as "pro tips"

• information
  • Used to bring awareness to helpful information

• success
  • Used to inform users of success or completion

• caution
  • Used to caution the user

• error
  • Used to inform users of dangerous actions, failures, or errors

• feature
  • Used to alert customers of something new or promote a call-to-action

Type

A banner contains 3 different style types:

• inline
  • Used to display a banner inline, along with the content it's related to
  • Styled with a subtle bottom border

• alert
  • A floating banner that communicates information about the whole page, or when there isn't one specific element to attach it to
  • Styled with a bottom border and a shadow

• announcement
  • A full-width banner appearing at the top of the app
  • Styled with no border, no border radius, and the content centered

Title

Use the title to efficiently communicate the core of the message. Starting a title with a short phrase ('Heads up!', 'Oh no!', 'Pro tip:', etc.) can help communicate the tone.

Description

The banner's body text can be provided with the description prop in React or the @description argument in Ember:

Rich description content, like links, may be passed into the description prop or Ember description named block:

Custom content

Regular React children and Ember default yielded content render directly in the banner content area. Use BannerTitle/BannerDescription or PlumaBannerTitle/PlumaBannerDescription when composing custom content that should match Banner title and description styles:

Icon

The banner will default to an icon that is appropriate for the chosen variant. The icon can be changed with the icon prop:

Be careful when choosing an icon to avoid miscommunication. For example, don't show a checkmark in a error banner.

Actions

Add a primary action to a banner when an action is possible outside of closing/dismissing the banner. The label for the action is customizable.

Example: Saving some data failed, so the user can try again from the alert.

The action prop accepts an object that represents either a link or a button. If the href key is present, the banner will render a link (styled like a button). Otherwise, a button will be rendered. The shape of the object is:

{
	label: string;
	href?: string;
	isExternal?: boolean;
	onClick?: () => void;
	isDisabled?: boolean;
	variant?: 'primary' | 'secondary' | 'tertiary' | 'subtle';
	isLoading?: boolean;
	autoLoading?: boolean;
}

or

{
	label: string;
	onClick?: () => void;
	isDisabled?: boolean;
	variant?: 'primary' | 'secondary' | 'tertiary' | 'subtle';
	isLoading?: boolean;
	autoLoading?: boolean;
}

The variant property allows you to customize the button's visual style. By default, banner action buttons use the "subtle" variant.

The isLoading property can be used to manually set the action button to a loading state, which shows a spinner and disables interactions. The autoLoading property (enabled by default) will automatically set the button to a loading state when the onClick handler returns a Promise, until that Promise resolves or rejects.

Dismiss button

Sometimes, you may also want to display a "dismiss" button along with the action. This can be accomplished by enabling shouldShowDismissButton and passing in an onClose callback (which will be called when the button is clicked):

Close button

As an alternative to the "dismiss" button, an "X" close button can be displayed. This can be enabled by passing in an onClose callback, but without enabling shouldShowDismissButton or customizing dismissButtonText:

Outlined style

By default, banners have a colored background. You can use the isOutlined prop to switch to an outlined style with a white background and a colored border: