Banner

Banners surface important information and feedback to the user about a task, action, or state.

GitHubStorybook
yarn add @workday/canvas-kit-react
Sources
GitHubStorybook
Install
yarn add @workday/canvas-kit-react

Anatomy

Image of an alert and error Banner in its default state.

  1. Icon: Supplementary visual indicator used to distinguish between error and alert Banners.
  2. Label: Total count of all errors and/or alerts on a page.
  3. Action Text (Conditional): Link text that indicates the Banner is actionable. Activating the link opens a list of all errors and alerts on a page. Action text is only available in the full Banner variant and has a default value of View All.
  4. Container: Colored container that houses the error or alert icon, message, and action text. The container can be full or sticky, in which the Banner is to be displayed along the right edge of the page.

Usage Guidance

Banners consist of errors and alerts:

  • Typically appearing in response to user action, errors prevent the user from moving forward in their process until the error is corrected. Common error triggers include failing to enter a value for required fields, entering values in a form that are incompatible, or when user input is not understood.
  • Alerts convey information the user should be aware of to help prevent a future error, but allow the user to proceed without addressing the alert.

When to Use

  • Use Banners to notify users of missteps that happen within a workflow and describe how the user can take appropriate action to resolve them.
  • Banners should bring a user’s attention to problems or mistakes either before they happen, or before the user can move on.

When to Use Something Else

  • Ideally, a design won’t create a scenario that causes the need for a Banner. If you can avoid these scenarios by mentioning information that will help in hint text, or by simplifying your design, always do so.

Do's and Don'ts

Do

Combine error and alert messages into a single error Banner.

Don't

Do not use separate error and alert Banners if there are both errors and alerts on the same page.

Examples

Basic Example

Use the children of Banner.Label to set the main text for the Banner.

Action Text

Use the children of Banner.ActionText to customize the action text contained in the Banner. The text has default value of View All.

Error Type

Set the hasError prop of the Banner to designate the severity of the message presented in the banner. This will change the defualt icon to exclamationCircleIcon.

Sticky

Set the isSticky prop of the Banner to display it along the right edge of the page. When true, the Banner.ActionText will be hidden. Some basic styles will be applied, but you will still need to manually set the css position value.

You can use keyframes to animate the Banner in.

RefForwarding

Banner supports ref forwarding. It will forward ref to its underlying button element.

Right-to-Left (RTL)

Banner supports right-to-left languages when specified in the CanvasProvider theme.

Themed Banners

Banners use the useThemedPalette hook for themeing. By default, your alert theme is used. main will be used for the background, dark for the hover background, and contrast for the text.

If you set the hasError prop, the banner will use your error theme.

Component API

Usage

Banner is a container component rendered as a <button> element that is responsible for creating a BannerModel and sharing it with its subcomponents using React context.

<Banner
isSticky={true}
hasError={true} id:
'custom-banner-id'
onClick={() => console.log('clicked banner')}
>
{/* Child components */}
</Banner>

Alternatively, you may pass in a model using the hoisted model pattern.

const model = useBannerModel({
isSticky: true,
hasError: true,
id: 'custom-banner-id',
});
return (
<Banner onClick={() => console.log('clicked banner')} model={model}>
{/* Child components */}
</Banner>
);

Props

Undocumented props are spread to the underlying <button> element.

NameTypeDefaultDescription

If you're using the hoisted model pattern, follow this table instead (refer to the Model section for more information about BannerModel):

NameTypeDefaultDescription
model*BannerModel

Banner.Icon

Usage

Banner.Icon is a styled <SystemIcon>. The icon defaults to exclamationTriangleIcon or exclamationCircleIcon when the model's hasError is true.

<Banner.Icon />

Props

You can override the default icon if needed.

Undocumented props are spread to the underlying <SystemIcon> element.

NameTypeDefaultDescription
iconCanvasSystemIcon | undefined`exclamationTriangleIcon` or `exclamationCircleIcon` when hasError is trueIcon to show next to label

Banner.Label

Usage

Banner.Label is a styled <Flex>. This component will get an id that will be used for the aria-describedby on the top level <button>.

<Banner.Label>3 Warnings</Banner.Label>

Props

The children prop will be used as the Primary text of the Banner.

Undocumented props are spread to the underlying <Flex> element.

NameTypeDefaultDescription
children*ReactNodeThe text of the Banner.

Banner.ActionText

Usage

Banner.ActionText is a styled <Box>. This component will get an id that will be used for the aria-labelledby on the top level <button>. This component will be visually hidden when the model's isSticky prop is set to true.

<Banner.ActionText>Custom call to action</Banner.ActionText>

Props

The children prop will be used as the 'call to action' text of the Banner.

Undocumented props are spread to the underlying <Box> element.

NameTypeDefaultDescription
childrenReactNode'View All'The text of the Banner action.

Model

If Banner was stripped of all its markup, attributes, and styling, what would remain is the model. The model is an object that holds the state, i.e. a description of the current snapshot in time of the component.

By default, Banner will create a model and share it internally with its subcomponents using React context. You may subscribe to BannerContext if you wish to create a custom subcomponent for your implementation. Here's a simple example.

import * as React from 'react';
import {Banner, BannerModelContext} from '@workday/canvas-kit-react/banner';
const CustomText = (props: React.HTMLAttributes<HTMLSpanElement>) => {
const model = React.useContext(BannerModelContext);
return <span {...props}>{model.state.hasError ? 'Error:' : 'Warning:'}</span>;
};
export const CustomBanner = () => {
return (
<Banner>
<CustomText />
{/* Other subcomponents */}
</Banner>
);
};

Alternatively, if you need direct access to the model's state outside of the Banner component, you may configure your own model with useBannerModel and pass it to Banner via a pattern called hoisting the model.

const model = useBannerModel({
isError: true,
});
<Banner model={model}>{/* Child components */}</Banner>;

Config

useBannerModel accepts a configuration object with the following properties and returns a BannerModel with a state property.

NameTypeDefaultDescription

Accessibility Guidelines

  • Avoid using color alone to differentiate between errors and alerts. Instead, use icons or text that says “Error” or “Alert.”
  • If both icons and visible text are used to differentiate between errors and alerts, the icons are considered redundant and should not provide any alternative text for screen readers.
  • When possible, error and alert states should provide information on how to fix issues or hints on fixing formatting.

Content Guidelines

  • When writing error or alert messages, refer to the Errors and Alerts section of the Content Style Guide.

Can't Find What You Need?

Check out our FAQ section which may help you find the information you're looking for.

FAQ Section