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"

<Banner title="Banner title" description="Banner content" />

• information
  • Used to bring awareness to helpful information

<Banner title="Banner title" description="Banner content" variant="information" />

• success
  • Used to inform users of success or completion

<Banner title="Banner title" description="Banner content" variant="success" />

• caution
  • Used to caution the user

<Banner title="Banner title" description="Banner content" variant="caution" />

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

<Banner title="Banner title" description="Banner content" variant="error" />

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

<Banner title="Banner title" description="Banner content" variant="feature" />

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

<Banner title="Banner title" description="Banner content" />

• 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

<Banner title="Banner title" description="Banner content" type="alert" />

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

<Banner title="Banner title" description="Banner content" type="announcement" onClose={() => {}} />

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.

<Banner title="Heads up!" description="Actually, never mind." />

Description

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

<Banner title="Banner title" description="This is the banner's description." />

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

<Banner
	title="Banner title"
	variant="information"
	description={
		<>
			This is the banner's description, this time with <Link href="https://customer.io" isExternal={true}>a link</Link>.
		</>
	}
/>

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:

<Banner variant="information">
	<BannerTitle>Composed banner</BannerTitle>
	<BannerDescription>
		This description uses the child component and contains <Link href="https://customer.io" isExternal={true}>a link</Link>.
	</BannerDescription>
</Banner>

Icon

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

<Banner title="Banner title" description="Banner content" icon="segment" />

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.

<Banner
	title="Banner title"
	description="Banner content"
	action={{
		label: 'Visit docs',
		href: 'https://customer.io/docs',
		isExternal: true
	}}
/>

<Banner
	title="Primary action example"
	description="A banner with a primary action button to attract attention"
	variant="feature"
	action={{
		label: 'Try new feature',
		variant: 'primary'
	}}
/>

<Banner
	title="Manual loading state"
	description="This banner has an action button in a loading state"
	variant="information"
	action={{
		label: 'Processing',
		isLoading: true
	}}
/>

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):

<Banner
	title="Banner title"
	description="Banner content"
	action={{
		label: 'Try again',
		onClick: () => alert('Trying again')
	}}
	shouldShowDismissButton={true}
	onClose={() => alert('Closing banner')}
/>

<Banner
	title="Banner title"
	description="Banner content"
	action={{
		label: 'Try again',
		onClick: () => alert('Trying again')
	}}
	dismissButtonText="Close"
	onClose={() => alert('Closing banner')}
/>

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:

<Banner
	title="Banner title"
	description="Banner content"
	type="announcement"
	variant="caution"
	onClose={() => alert('Closing banner')}
/>

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:

<Banner
	title="Default filled style"
	description="This banner has the default filled style with a colored background."
	variant="information"
/>

<Banner
	title="Outlined style"
	description="This banner has an outlined style with a white background and colored border."
	variant="information"
	isOutlined={true}
/>