Action Bar

Anatomy

1. Primary Button: A button that is discoverable and used as the most important action to take on a page.
2. Secondary Button: A button or set of buttons that is less important than the Primary Button.
3. Overflow Menu: An Icon-Only Secondary Button Variant with an Ellipsis Icon used for responsive screens or small page width to show more actions.
4. Container Bar: The Container Bar is used to house action buttons and is anchored at the bottom of the screen.

Usage Guidance

• Primary Buttons should only be used once per screen. If there are other buttons on screen, use the Secondary or Tertiary Buttons. However, Tertiary Buttons should not be on the Action Bar unless it’s in the Overflow Menu.
• Action Bars are placed at the bottom of the screen, and will stick as the user scrolls.
• Although actions may change, the placement of the Action Bar should persist until the task is successfully submitted.
• Action Bars can contain up to 3 actions and an Overflow Menu when appropriate.
• If there are more than 3 actions, hide the 4th and other remaining actions in an Overflow Menu that is launched by clicking the Icon Only Secondary Button Variant.
• There should be between 1-7 items to choose from in an Overflow Menu.
• Buttons placed in Action Bars should be grouped logically, either by usage or importance.

When to Use

• Use Action Bars for tasks that require navigating between pages, saving progress, submitting a task, or cancelling a task.

When to Use Something Else

• Consider taking a Button outside of the Action Bar if the action is not related to the progress or status of a task.
• Consider using a Text Button instead of an Action Bar if an action is less popular or less important.

Examples

Basic Example

ActionBar includes a container ActionBar component and the following subcomponent: ActionBar.List which should contains ActionBar.Item.

In a basic example of an ActionBar there are two buttons. The primary action button should be used only once and left aligned if content is left to right, followed by secondary buttons. Tertiary buttons should not be used in the Action Bar.

import {ActionBar} from '@workday/canvas-kit-react/action-bar';
import {PrimaryButton} from '@workday/canvas-kit-react/button';

export default () => {
  return (
    <ActionBar>
      <ActionBar.List position="relative" as="section" aria-label="Action Bar">
        <ActionBar.Item as={PrimaryButton} onClick={() => console.log('first action')}>
          First Action
        </ActionBar.Item>
        <ActionBar.Item>Second Action</ActionBar.Item>
      </ActionBar.List>
    </ActionBar>
  );
};

Icons Example

ActionBar.Item renders a SecondaryButton as default, so it’s possible to use other Button props with ActionBar.Item such as icon or size.

import {ActionBar} from '@workday/canvas-kit-react/action-bar';
import {notificationsIcon, alarmClockIcon} from '@workday/canvas-system-icons-web';
import {PrimaryButton} from '@workday/canvas-kit-react/button';

export default () => {
  return (
    <ActionBar>
      <ActionBar.List position="relative" as="section" aria-label="Action Bar">
        <ActionBar.Item as={PrimaryButton} icon={notificationsIcon}>
          First Action
        </ActionBar.Item>
        <ActionBar.Item icon={alarmClockIcon}>Second Action</ActionBar.Item>
      </ActionBar.List>
    </ActionBar>
  );
};

Delete Action Example

ActionBar.Item is a SecondaryButton by default but it’s posible to change it to another element, such as DeleteButton, by using as prop.

import {ActionBar} from '@workday/canvas-kit-react/action-bar';
import {DeleteButton} from '@workday/canvas-kit-react/button';

export default () => {
  return (
    <ActionBar>
      <ActionBar.List position="relative" as="section" aria-label="Action Bar">
        <ActionBar.Item as={DeleteButton}>Delete Action</ActionBar.Item>
        <ActionBar.Item>Second Action</ActionBar.Item>
      </ActionBar.List>
    </ActionBar>
  );
};

Overflow Example

ActionBar container can contain up to 3 actions and an Overflow Menu if there are more than 3 actions, the other remaining actions should be placed into an Overflow Menu that is launched by clicking the Overflow Button.

Also, ActionBar is a responsive component based on the width of its container. If the rendered actions exceed the width of the ActionBar.List, an overflow menu will be rendered. This only works against the dynamic API where you give the ActionBarModel an array of items to be rendered. The dynamic API handles the React key for you based on the item’s identifier. The dynamic API requires either an id on each item object or a getId function that returns an identifier based on the item. The below example uses an id property on each item.

The dynamic API takes in any object, but since nothing is known about your object, a render prop is necessary to instruct a list how it should render.

import React from 'react';
import {breakpoints} from '@workday/canvas-kit-react/common';
import {ActionBar, useActionBarModel} from '@workday/canvas-kit-react/action-bar';
import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {SegmentedControl} from '@workday/canvas-kit-preview-react/segmented-control';
import {Box} from '@workday/canvas-kit-react/layout';

type MyActionItem = {
  id: string;
  text: React.ReactNode;
};

export default () => {
  const [items] = React.useState<MyActionItem[]>([
    {id: 'first', text: 'First Action'},
    {id: 'second', text: 'Second Action'},
    {id: 'third', text: 'Third Action'},
    {id: 'fourth', text: 'Fourth Action'},
    {id: 'fifth', text: 'Fifth Action'},
  ]);

  const model = useActionBarModel({items});
  const [containerWidth, setContainerWidth] = React.useState<string | number>('100%');

  return (
    <div>
      <Box maxWidth={containerWidth} marginBottom="xl">
        <ActionBar model={model}>
          <ActionBar.List
            position="relative"
            as="section"
            aria-label="Action Bar"
            overflowButton={<ActionBar.OverflowButton aria-label="More actions" />}
          >
            {(item: MyActionItem, index) => (
              <ActionBar.Item
                as={index === 0 ? PrimaryButton : undefined}
                onClick={() => console.log(item.id)}
              >
                {item.text}
              </ActionBar.Item>
            )}
          </ActionBar.List>
          <ActionBar.Menu.Popper>
            <ActionBar.Menu.Card maxWidth={300} maxHeight={200}>
              <ActionBar.Menu.List>
                {(item: MyActionItem) => (
                  <ActionBar.Menu.Item onClick={() => console.log(item.id)}>
                    {item.text}
                  </ActionBar.Menu.Item>
                )}
              </ActionBar.Menu.List>
            </ActionBar.Menu.Card>
          </ActionBar.Menu.Popper>
        </ActionBar>
      </Box>
      <footer>
        <h4>Change Action Bar container size</h4>
        <SegmentedControl onSelect={data => setContainerWidth(data.id)}>
          <SegmentedControl.List role="group" aria-label="container width control" marginBottom="m">
            <SegmentedControl.Item data-id="100%">100%</SegmentedControl.Item>
            <SegmentedControl.Item data-id={`${breakpoints.m}px`}>Small</SegmentedControl.Item>
            <SegmentedControl.Item data-id="420px">420px</SegmentedControl.Item>
            <SegmentedControl.Item data-id={`${breakpoints.s}px`}>
              Extra Small
            </SegmentedControl.Item>
          </SegmentedControl.List>
        </SegmentedControl>
        <p>Selected: {containerWidth}</p>
      </footer>
    </div>
  );
};

The number of visible buttons can also be adjusted by using the model’s maximumVisible attribute. You can change it from the default of 3 to any number greater than 1 and less than items.length.

import React from 'react';
import {ActionBar} from '@workday/canvas-kit-react/action-bar';

type MyActionItem = {
  id: string;
  text: React.ReactNode;
};

export default () => {
  const [items] = React.useState<MyActionItem[]>([
    {id: 'view', text: 'View'},
    {id: 'edit', text: 'Edit'},
    {id: 'delete', text: 'Delete'},
  ]);

  return (
    <ActionBar items={items} maximumVisible={2}>
      <ActionBar.List
        as="section"
        aria-label="Custom button count overflow example"
        position="relative"
        overflowButton={<ActionBar.OverflowButton aria-label="More actions" />}
      >
        {(item: MyActionItem) => (
          <ActionBar.Item onClick={() => console.log(item.id)}>{item.text}</ActionBar.Item>
        )}
      </ActionBar.List>
      <ActionBar.Menu.Popper>
        <ActionBar.Menu.Card>
          <ActionBar.Menu.List>
            {(item: MyActionItem) => (
              <ActionBar.Menu.Item onClick={() => console.log(item.id)}>
                {item.text}
              </ActionBar.Menu.Item>
            )}
          </ActionBar.Menu.List>
        </ActionBar.Menu.Card>
      </ActionBar.Menu.Popper>
    </ActionBar>
  );
};

Accessibility

Grouping the actions into an HTML <section> element with an aria-label string is recommended. This can be useful for helping screen reader users quickly jump down to the actions at the bottom of a page.

Refer to Button and Menus for more information about accessibiliy of these components in the Action Bar.

Component API

<ActionBar items={[]}>{Child components}</ActionBar>

const model = useActionBarModel({
  items: [],
});

<ActionBar model={model}>{Child components}</ActionBar>;

// without overflow
<ActionBar.List>{ActionBar.Items}</ActionBar.List>

// with overflow
<ActionBar.List overflowButton={<ActionBar.OverflowButton aria-label="More actions"/>}>
  {ActionBar.Items}
</ActionBar.List>

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

<ActionBar.Item as={PrimaryButton} onClick={() => console.log('first action')}>
  First Action
</ActionBar.Item>

<ActionBar.Item>First Action</ActionBar.Item>

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

Menu

Content Guidelines

• When naming buttons within an Action Bar, refer to the Buttons and Calls to Action section of the Content Style Guide.

Anatomy

1. Primary Button: Used as the most important action on a page or task.
2. Secondary Button: Actions that are less important than Primary Buttons.
3. Overflow Button: A Secondary Icon-Only Button that opens an Overflow Menu.
4. Bar Container: Container that groups buttons, anchored to the bottom of the screen.

Variations

Mobile

Mobile action bars can contain up to one Primary Button and one Secondary Button, with additional actions placed in an Overflow Menu.

Overflow

In the case of more than two calls to action in the bar, any overflowing actions should be placed in the Overflow Menu. Tapping on the Overflow Button will open a Menu with those Secondary or Tertiary Actions.

If the text within the Primary Button is too long to fit, the Secondary or Tertiary button(s) should move into the Overflow Menu to allow room for a full-width Primary Button.

Vertical Button Stack

While the horizontal stack is the default and preferred configuration, the buttons will automatically display in a vertical stack when truncation occurs within button labels. Alternatively if your use case places a priority on the action bar (E.g. empty states) you can use the vertical stack regardless of the truncation rule. When using the vertical stack be aware of previous or following page layouts that may be using a horizontal stack resulting in inconsistent layouts. The vertical stack is only available for phones; it’s not applicable to tablets.

Tablet

Action Bars on tablets may include up to one Primary and two Secondary Buttons.

Overflow

In the case of more than two calls to action in the bar, all overflowing actions should be placed in the Overflow Menu. Tapping on the Overflow Button will open a Menu containing those Secondary or Tertiary Actions.

If the Primary Button length is too long to fit the Secondary Button beside it, the Secondary Button should be placed in the Overflow Menu.

Usage Guidance

• There should only be one Primary Button in the Action Bar. If there are additional actions, use Secondary Buttons. Tertiary Buttons should only appear as actions in the Overflow Menu.
• Action Bars are placed at the bottom of the screen. If there is scrollable content, the Action Bar should remain sticky as the user scrolls.
• Although actions may change, the placement of the Action Bar should persist until the task is successfully submitted.
• Mobile Action Bars can contain up to two visible actions. If there are more than two actions, hide the third and any other actions in an Overflow Menu that is launched by tapping on the Icon Only Secondary Button Variant.
• Tablet Action Bars can contain up to three visible actions. If there are more than three actions, hide the fourth and any other actions in an Overflow Menu that is launched by tapping on the Icon Only Secondary Button Variant.
• Limit the Overflow Menu to a maximum of seven items.
• Group buttons in Action Bars logically, either by usage or ordered by importance.

When to Use

• Use Action Bars for tasks that require navigating between pages, saving progress, submitting a task, or canceling a task.

When to Use Something Else

• Consider taking a Button outside of the Action Bar if the action is not related to the progress or status of a task.
• Consider using a Tertiary Button instead of an Action Bar if an action is less popular or less important.
• If actions are not related to a full screen task, consider using a group of buttons instead.

Mobile Guidance

Button Placement

Mobile Action Bars place Primary Buttons on the right-most side to account for a majority of right handed users.

Button Resizing

Buttons in Mobile Action Bars stretch to fit the entire screen width, respecting padding and spacing tokens.

Only Show Depth if Content is Scrollable

If there is scrollable content, provide scrolling indication through use of Depth. If there is no scrollable content, no Depth is used on the Action Bar with a plain French Vanilla 100 background.

Device Considerations

8dp of bottom padding is taken away from the action bar if it’s rendered on a iPhoneX to account for the extra spacing for the home indicator.

Text Overflow

Buttons within Actions Bars should never wrap to multiple lines. Instead, truncate text when Buttons reach screen margins.

API Guidelines

Methods

Class name: ActionBarV2 Module name: UIComponentsPlugin

public init(
	actions: [ActionBarItemModel],
	style: ActionBarV2Internal.Style = .regular,
	isContentScrollable: Bool = false,
  localizer: LocalizationAdapting,
	featureData: FeatureMetricsData
)

Adds an ActionBar to any content as per Workday design requirements.

Parameters

Content Guidelines

• When naming buttons within an Action Bar, refer to the Buttons and Calls to Action section of the Content Style Guide.

Anatomy

1. Primary Button: Used as the most important action on a page or task.
2. Secondary Button: Actions that are less important than Primary Buttons.
3. Overflow Button: A Secondary Icon-Only Button that opens an Overflow Menu.
4. Bar Container: Container that groups buttons, anchored to the bottom of the screen.

Variations

Mobile

Mobile action bars can contain up to one Primary Button and one Secondary Button, with additional actions placed in an Overflow Menu.

Overflow

In the case of more than two calls to action in the bar, all overflowing actions should be placed in the Overflow Menu. Tapping on the Overflow Button will open a Menu with those Secondary or Tertiary Actions.

If the text within the Primary Button is too long to fit, the Secondary or Tertiary button(s) should move into the Overflow Menu to allow room for a full-width Primary Button.

Vertical Button Stack

While the horizontal stack is the default and preferred configuration, the buttons will automatically display in a vertical stack when truncation occurs within button labels. Alternatively if your use case places a priority on the action bar (E.g. empty states) you can use the vertical stack regardless of the truncation rule. When using the vertical stack be aware of previous or following page layouts that may be using a horizontal stack resulting in inconsistent layouts. The vertical stack is only available for phones; it’s not applicable to tablets.

Usage Guidance

• There should only be one Primary Button in the Action Bar. If there are additional actions, use Secondary Buttons. Tertiary Buttons should only appear as actions in the Overflow Menu.
• Action Bars are placed at the bottom of the screen. If there is scrollable content, the Action Bar should remain sticky as the user scrolls.
• Although actions may change, the placement of the Action Bar should persist until the task is successfully submitted.
• Mobile Action Bars can contain up to two visible actions. If there are more than two actions, hide the third and any other actions in an Overflow Menu that is launched by tapping on the Icon Only Secondary Button Variant.
• Tablet Action Bars can contain up to three visible actions. If there are more than three actions, hide the fourth and any other actions in an Overflow Menu that is launched by tapping on the Icon Only Secondary Button Variant.
• Limit the Overflow Menu to a maximum of seven items.
• Group buttons in Action Bars logically, either by usage or ordered by importance.

When to Use

• Use Action Bars for tasks that require navigating between pages, saving progress, submitting a task, or canceling a task.

When to Use Something Else

• Consider taking a Button outside of the Action Bar if the action is not related to the progress or status of a task.
• Consider using a Tertiary Button instead of an Action Bar if an action is less popular or less important.
• If actions are not related to a full screen task, consider using a group of buttons instead.

Mobile Guidance

Button Placement

Mobile Action Bars place Primary Buttons on the right-most side to account for a majority of right handed users.

Button Resizing

Buttons in Mobile Action Bars stretch to fit the entire screen width, respecting padding and spacing tokens.

Only Show Depth if Content is Scrollable

If there is scrollable content, provide scrolling indication through use of Depth. If there is no scrollable content, no Depth is used on the Action Bar with a plain French Vanilla 100 background.

Device Considerations

8dp of bottom padding is taken away from the action bar if it’s rendered on a iPhoneX to account for the extra spacing for the home indicator.

Text Overflow

Buttons within Actions Bars should never wrap to multiple lines. Instead, truncate text when Buttons reach screen margins.

API Guidelines

Component Definition

@Composable
fun [ActionBarUiComponent](
    modifier: Modifier = Modifier,
    numButtonsShown: [Int] = 1,
    isScrollable: [Boolean](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-boolean/index.html) = true,
    buttonList: [List]<[ActionBarButtonItem]>
) {

Parameters

Content Guidelines

• When naming buttons within an Action Bar, refer to the Buttons and Calls to Action section of the Content Style Guide.