Banner

Anatomy

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

Examples

Basic Example

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

import React from 'react';

import {Banner} from '@workday/canvas-kit-react/banner';

export default () => {
  return (
    <Banner onClick={() => console.log('clicked banner')}>
      <Banner.Icon />
      <Banner.Label>3 Warnings</Banner.Label>
      <Banner.ActionText />
    </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.

import React from 'react';

import {Banner} from '@workday/canvas-kit-react/banner';

export default () => {
  return (
    <Banner>
      <Banner.Icon />
      <Banner.Label>3 Warnings</Banner.Label>
      <Banner.ActionText>Show Details</Banner.ActionText>
    </Banner>
  );
};

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.

import {Banner} from '@workday/canvas-kit-react/banner';

export default () => {
  return (
    <Banner hasError={true}>
      <Banner.Icon />
      <Banner.Label>3 Errors</Banner.Label>
      <Banner.ActionText />
    </Banner>
  );
};

Icon Banner

When only using an icon in the Banner, use our Tooltip component to both show a visible text alternative, and assign an aria-label string to the child Banner.

import React from 'react';

import {Banner} from '@workday/canvas-kit-react/banner';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {styled} from '@workday/canvas-kit-react/common';

export default () => {
  return (
    <Tooltip title="Warning">
      <Banner width="4em">
        <Banner.Icon />
      </Banner>
    </Tooltip>
  );
};

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.

import {Box} from '@workday/canvas-kit-react/layout';
import {Banner} from '@workday/canvas-kit-react/banner';
import {styled} from '@workday/canvas-kit-react/common';

const StyledBanner = styled(Banner)({
  position: 'absolute',
  right: 0,
});

export default () => {
  return (
    <Box height={64}>
      <StyledBanner hasError={true} isSticky={true}>
        <Banner.Icon />
        <Banner.Label>3 Errors</Banner.Label>
        <Banner.ActionText />
      </StyledBanner>
    </Box>
  );
};

You can use keyframes to animate the Banner in.

import React from 'react';

import {useTheme} from '@workday/canvas-kit-react/common';
import {Box} from '@workday/canvas-kit-react/layout';
import {loopIcon} from '@workday/canvas-system-icons-web';
import {Banner} from '@workday/canvas-kit-react/banner';
import {
  createStencil,
  createStyles,
  createVars,
  keyframes,
  handleCsProp,
  cssVar,
} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const containerStyles = createStyles({
  position: 'absolute',
  right: 0,
  overflow: 'hidden',
});
const stickyAnimationVars = createVars('width', 'rerun');
const stickAnimationKeyframes = keyframes({
  '0%': {
    transform: `translateX(${cssVar(stickyAnimationVars.width)})`,
  },
  '100%': {
    transform: `translateX(0 * ${cssVar(stickyAnimationVars.rerun)})`,
  },
});

const stickyAnimationStencil = createStencil({
  base: {
    marginBlock: system.space.x1,
    marginInlineStart: system.space.x1,
    marginInlineEnd: 0,
    animationName: stickAnimationKeyframes,
    animationDuration: '.3s',
    animationTimingFunction: 'ease-out',
  },
});

export default () => {
  const theme = useTheme();
  const bannerRef = React.useRef<HTMLButtonElement>(null);
  const containerRef = React.useRef<HTMLDivElement>(null);
  const [bannerWidth, setBannerWidth] = React.useState(0);

  const [rerun, setRerun] = React.useState(1); // Only needed for demo purposes

  React.useLayoutEffect(() => {
    const width = bannerRef.current.offsetWidth;
    setBannerWidth(theme.canvas.direction === 'rtl' ? width * -1 : width);
  }, [theme.canvas.direction, rerun]);

  return (
    <Box height={64}>
      <div className={containerStyles} ref={containerRef}>
        <div
          key={rerun}
          {...handleCsProp({}, [
            stickyAnimationStencil(),
            stickyAnimationVars({width: `${bannerWidth}px`, rerun: `${rerun}`}),
          ])}
        >
          <Banner
            onClick={() => setRerun(r => r + 1)}
            hasError={true}
            isSticky={true}
            ref={bannerRef}
          >
            <Banner.Icon icon={loopIcon} />
            <Banner.Label>Click to run animation</Banner.Label>
            <Banner.ActionText />
          </Banner>
        </div>
      </div>
    </Box>
  );
};

RefForwarding

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

import React from 'react';

import {changeFocus} from '@workday/canvas-kit-react/common';
import {Banner} from '@workday/canvas-kit-react/banner';
import {SecondaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';

export default () => {
  const bannerRef = React.useRef<HTMLButtonElement>(null);

  const focusBanner = () => {
    changeFocus(bannerRef.current);
  };

  return (
    <Flex flexDirection="column" gap="xs" alignItems="flex-start">
      <Banner ref={bannerRef}>
        <Banner.Icon />
        <Banner.Label>3 Warnings</Banner.Label>
        <Banner.ActionText />
      </Banner>
      <SecondaryButton onClick={focusBanner}>Focus Banner</SecondaryButton>
    </Flex>
  );
};

Right-to-Left (RTL)

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

import React from 'react';

import {Box} from '@workday/canvas-kit-react/layout';
import {CanvasProvider, styled} from '@workday/canvas-kit-react/common';
import {Banner} from '@workday/canvas-kit-react/banner';

const StyledStickyBanner = styled(Banner)({
  position: 'absolute',
  right: 0,
});

export default () => {
  return (
    <CanvasProvider dir="rtl">
      <Box height={64}>
        <StyledStickyBanner isSticky={true}>
          <Banner.Icon />
          <Banner.Label>3 אזהרות</Banner.Label>
          <Banner.ActionText />
        </StyledStickyBanner>
      </Box>
    </CanvasProvider>
  );
};

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.

import React from 'react';

import {Banner} from '@workday/canvas-kit-react/banner';
import {CanvasProvider, PartialEmotionCanvasTheme} from '@workday/canvas-kit-react/common';
import {colors} from '@workday/canvas-kit-react/tokens';

export default () => {
  const theme: PartialEmotionCanvasTheme = {
    canvas: {
      palette: {
        alert: {
          main: colors.kiwi200,
          dark: colors.kiwi300,
        },
      },
    },
  };

  return (
    <CanvasProvider theme={theme}>
      <Banner>
        <Banner.Icon />
        <Banner.Label>3 Items</Banner.Label>
        <Banner.ActionText />
      </Banner>
    </CanvasProvider>
  );
};

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

import React from 'react';

import {Banner} from '@workday/canvas-kit-react/banner';
import {CanvasProvider, PartialEmotionCanvasTheme} from '@workday/canvas-kit-react/common';
import {colors} from '@workday/canvas-kit-react/tokens';

export default () => {
  const theme: PartialEmotionCanvasTheme = {
    canvas: {
      palette: {
        error: {
          main: colors.islandPunch500,
          dark: colors.islandPunch600,
          contrast: colors.berrySmoothie100,
        },
      },
    },
  };

  return (
    <CanvasProvider theme={theme}>
      <Banner hasError={true}>
        <Banner.Icon />
        <Banner.Label>3 Items</Banner.Label>
        <Banner.ActionText />
      </Banner>
    </CanvasProvider>
  );
};

Component API

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

const model = useBannerModel({
  isSticky: true,
  hasError: true,
  id: 'custom-banner-id',
});

return (
  <Banner onClick={() => console.log('clicked banner')} model={model}>
    {Child components}
  </Banner>
);

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

<Banner.Icon />

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

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

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

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

import {handleCsProp} from '@workday/canvas-kit-styling';
import {mergeStyles} from '@workday/canvas-kit-react/layout';

// ...

// `handleCsProp` handles compat mode with Emotion's runtime APIs. `mergeStyles` has the same
// function signature, but adds support for style props.

return (
 <Element
   {...handleCsProp(elemProps, [
     myStyles,
     myModifiers({ size: 'medium' }),
     myVars({ backgroundColor: 'red' })
   ])}
 >
   {children}
 </Element>
)

Accessibility Guidelines

How Banners Impact the Accessible Experience

Banner components can introduce accessibility barriers to successfully and accurately completing forms when accessibility is neglected. Users must be able to navigate to, and activate, a Banner component without using a mouse or trackpad. Banners must be keyboard focusable in the order they are appearing visually on screen. (Logical, left to right, top to bottom for left to right languages.)

When Banners appear on form submission, or from another explicit action by the user, setting keyboard focus onto the Banner can be a helpful way of guiding the interaction.

When Banners are generated by the system, or when users focus out of form fields, then it is not appropriate to move keyboard focus in these scenarios. This can be very disruptive, and may block users from completing their task.

Keyboard Interaction

Each Banner must have a focus indicator that is highly visible against the background and against the non-focused state. Refer to Accessible Colors for more information.

Keyboard focus must be set to the Banner component when it appears after a form submission, but do not force any focus movements on other events such as blur or change.

Banners must support the following keyboard interactions:

• Tab: focus the Banner element
• Enter or Space: activate the Banner element

Screen Reader Interaction

Banners must communicate the following to users:

• The text displayed inside the Banner
• The Banner is either an “alert” or an “error”
• The Banner is an interactive “button” element

Design Annotations Needed

• Specify the Banner’s error type: Alert or Error
• Specify the keyboard focus order for the Banner in context of the page
• Write the text alternative for the Icon when it conveys information to users. Read more about Non-Text Content

Implementation Markup Needed

• When the Banner Icon requires text alternative, set ARIA role=”img” and an aria-label string describing the Icon.
• Banner must be rendered in the DOM structure relative to where it is positioned visually on screen for the best keyboard focus accessibility.
• When a Banner is generated from a user action, set keyboard focus to the Banner.
• When a Banner is generated by the system, avoid moving the keyboard focus away from users’ context. Instead, use an aria-live region in the DOM to send the Banner message for screen readers to announce in real-time.

Content Guidelines

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

Anatomy

1. Icon: Added visual to support the overall message and stress the severity. These icons are specific to the type of banner and are not configurable.
2. Title: Summarized description of the main purpose of the banner.
3. Message: Main content describing the purpose of the banner in more detail. This message should be short and concise.
4. Buttons: Any Primary or Secondary actions of the banner.
5. Container: Houses all banner elements. Color may vary based on type of messaging.
6. Input Labels: Highlights the specific location of an error/warning using the title of the input in question. The number of labels displayed at once is limited due to space.
7. Counter: Shows total number of errors on the page, including all hidden errors. Counter hides when the number of errors is small enough to fit all within the banner.
8. Divider: Visually helps separate the content from the upper half and the lower half.

Usage Guidance

When to Use

• To communicate multiple validation errors/warnings related to the current task/page.
• To communicate errors/warnings about system processes (for example, loading, fetching or rendering issues) that require constant maintenance by the user. Banners do not disappear unless the user resolves the required action(s).

When to Consider Something Else

• If the issue is a validation error tied directly to a specific input use an standard inline error. See any input for more info.
• For single validation issues it is recommended to immediately focus the input where the error occurs, negating the need to display a banner in the first place.
• If communicating feedback about minor processes of the application, use a Snackbar.
• If information is critical and requires user action or decision, consider using an Alert Dialog. Alert Dialogs are reserved for messages of the highest priority; they command user action by blocking any other interactions.
• When no content can display on a page (due to a server error or connectivity issue, for example), use an Empty State, use the full page to communicate the status of the feature or to help educate users about its purpose. Empty states should include a message.

Behaviors

Specific guidance on how the component behaves. Include screenshots when appropriate.

Positioning

Banners are fixed at the top of the page directly below the Top App Bar, but live at the same level as the Top App Bar. They are persistent and until user interaction resolves the reason for the banner to be there.

Modality

Banners are non-modal messages, meaning they do not block the user from interacting with the rest of the page content, unlike Alert Dialogs. So users can continue to scroll or interact with any other element on the page.

Multiple Warnings or Alerts

Only one banner may be displayed at a time. Multiple validation warnings or errors should be consolidated within one error banner. If multiple non-validation issues occur at the same time, display the most severe issue first in a single banner. Once that issue has been addressed present another banner for each subsequent issue.

Examples

Single Error/Warning Variations

Use the single variations for all standard non-validation issues. These include loading, fetching or rendering issues, and other system wide issues that require constant maintenance by the user.

Multi-Error

Use when multiple validation issues exist on the current page need to be communicated to the user. If both errors and warnings are present at the same time they should be combined into the error variation to stress the severity. The multi-error variation first appears on screen in the collapsed state, requiring the user to reveal all the issues if they so choose.

Multi-Error Expanded

When a user taps on the “Show Errors” button the lower portion expands revealing, a space limited view of, all the errors/warnings. A counter is provided to communicate the total amount of errors preceded by the number of errors visible within the banner. Tapping on any input label within the banner should automatically scroll the page to the input in question. When errors are resolved by the user, the labels are dynamically removed from the section, with the Banner closing once all errors have been resolved.

API Guidelines

Methods

Class name: Banner Module name: UIComponentsPlugin

    public init(
        featureData: FeatureMetricsData,
        title: String,
        message: String?,
        bannerType: BannerType,
        mainButton: BannerButtonItem? = nil,
        auxiliaryButton: BannerButtonItem? = nil,
        errorsList: Binding<[BannerButtonItem]> = Binding.constant([]),
        localizer: LocalizationAdapting,
        shouldShowBanner: Bool = true
    )

Parameters

Accessibility Guidelines

Coming Soon!

Content Guidelines

• Messages in banners should be short and concise, preferably up to 2 lines. Additional lines may be needed to support other languages with longer characters.
• In titles, avoid apologies (i.e., sorry, please, etc…), or additional written level of emphasis (e.g., warning).
• See Error and Alert Messages in the UI Text Section of Content Style Guide for additional language guidelines.

Anatomy

1. Icon: Added visual to support the overall message and stress the severity. These icons are specific to the type of banner and are not configurable.
2. Title: Summarized description of the main purpose of the banner.
3. Message: Main content describing the purpose of the banner in more detail. This message should be short and concise.
4. Buttons: Any Primary or Secondary actions of the banner.
5. Container: Houses all banner elements. Color may vary based on type of messaging.
6. Input Labels: Highlights the specific location of an error/warning using the title of the input in question. The number of labels displayed at once is limited due to space.
7. Counter: Shows total number of errors on the page, including all hidden errors. Counter hides when the number of errors is small enough to fit all within the banner.
8. Divider: Visually helps separate the content from the upper half and the lower half.

Usage Guidance

When to Use

• To communicate multiple validation errors/warnings related to the current task/page.
• To communicate errors/warnings about system processes (for example, loading, fetching or rendering issues) that require constant maintenance by the user. Banners do not disappear unless the user resolves the required action(s).

When to Consider Something Else

• If the issue is a validation error tied directly to a specific input use an standard inline error. See any input for more info.
• For single validation issues it is recommended to immediately focus the input where the error occurs, negating the need to display a banner in the first place.
• If communicating feedback about minor processes of the application, use a Snackbar.
• If information is critical and requires user action or decision, consider using an Alert Dialog. Alert Dialogs are reserved for messages of the highest priority; they command user action by blocking any other interactions.
• When no content can display on a page (due to a server error or connectivity issue, for example), use an Empty State, use the full page to communicate the status of the feature or to help educate users about its purpose. Empty states should include a message.

Behaviors

Specific guidance on how the component behaves. Include screenshots when appropriate.

Positioning

Banners are fixed at the top of the page directly below the Top App Bar, but live at the same level as the Top App Bar. They are persistent and until user interaction resolves the reason for the banner to be there.

Modality

Banners are non-modal messages, meaning they do not block the user from interacting with the rest of the page content, unlike Alert Dialogs. So users can continue to scroll or interact with any other element on the page.

Multiple Warnings or Alerts

Only one banner may be displayed at a time. Multiple validation warnings or errors should be consolidated within one error banner. If multiple non-validation issues occur at the same time, display the most severe issue first in a single banner. Once that issue has been addressed present another banner for each subsequent issue.

Examples

Single Error

Use the single variations for all standard non-validation issues. These include loading, fetching or rendering issues, and other system wide issues that require constant maintenance by the user.

Multi-Error

Use when multiple validation issues exist on the current page need to be communicated to the user. If both errors and warnings are present at the same time they should be combined into the error variation to stress the severity. The multi-error variation first appears on screen in the collapsed state, requiring the user to reveal all the issues if they so choose.

Multi-Error Expanded

When a user taps on the “Show Errors” button the lower portion expands revealing, a space limited view of, all the errors/warnings. A counter is provided to communicate the total amount of errors preceded by the number of errors visible within the banner. Tapping on any input label within the banner should automatically scroll the page to the input in question. When errors are resolved by the user, the labels are dynamically removed from the section, with the Banner closing once all errors have been resolved.

API Guidelines

Component Definition

@Composable
fun BannerUiComponent(
    modifier: Modifier = Modifier,
    bannerType: BannerType,
    title: String,
    message: String? = null,
    primaryButton: BannerButtonItem? = null,
    secondaryButton: BannerButtonItem? = null,
    errorList: List<BannerButtonItem>? = null,
    shouldShowBanner: Boolean = true
) {

Parameters

Accessibility Guidelines

Coming Soon!

Content Guidelines

• Messages in banners should be short and concise, preferably up to 2 lines. Additional lines may be needed to support other languages with longer characters.
• In titles, avoid apologies (i.e., sorry, please, etc…), or additional written level of emphasis (e.g., warning).
• See Error and Alert Messages in the UI Text Section of Content Style Guide for additional language guidelines.