Button

Buttons highlight actions available on a screen.

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

Anatomy

Image of a Primary and Secondary Button with annotation markers.

  1. Container (Conditional): Houses the contents of the Button. Visual appearance differs based on button type.
  2. Label (Conditional): Specific text describing the action. Refer to the Buttons and Calls to Action section of the Content Style Guide.
  3. Icon (Conditional): Supplementary visual indicator that can be positioned alone or added to the left or right of the label. Supplemental icons are used to promote the purpose of the Button.

Usage Guidance

  • Buttons should indicate an action.
  • They should be discoverable, easy to identify, and specific.
  • Make Buttons look and feel clickable.
  • Icons can be used alone or added to the left or right of the label. If used, the icon should signify what the Button does.
  • Use icon-only variants in dense environments or when space is limited.
  • Use accessible tooltips with icon-only variants to help explain ambiguous icons for everyone.
  • When deciding which Button to use, consider the level of priority of the action, as well as how much visual emphasis the Button should have in the context of the page it will live on. Be intentional and refer to the examples below to determine which is right for your use case.

When to Use Something Else

Examples

PrimaryButton

The example below shows multiple instances of a PrimaryButton with various icon configurations.

Primary Buttons also have an inverse variant. While it looks similar to the default Secondary Button, the default outline as well as the hover and focus states are different. Use this variant when you need to place a Primary Button on a dark or colorful background such as blueberry400.

SecondaryButton

The example below shows multiple instances of a SecondaryButton with various icon configurations.

Secondary Buttons also have an inverse variant. Use this when you need to place a Secondary Button on a dark or colorful background such as blueberry400.

TertiaryButton

The example below shows multiple instances of a TertiaryButton with various icon configurations.

Tertiary Buttons also have an inverse variant. Use this when you need to place a Tertiary Button on a dark or colorful background such as blueberry400.

DeleteButton

Use sparingly for destructive actions that will result in data loss, can’t be undone, or will have significant consequences. They commonly appear in confirmation dialogs as the final confirmation before deleting.

Custom Styles

We understand that there are instances in which consumers might need to adjust styles for specific use cases. All of our buttons extend our lower level base button props which extends style properties that come from Box. Below are some examples in which you can overwrite styles for all of our buttons. Please use this sparingly and try to adhere to the design system.

Accessible Use of the as Prop

Like many of our components, Buttons accept an as prop, which lets you change the underlying semantic element - usually an <a>, or a <button>. This should be done with caution to ensure the best accessibility. Generally, <button> elements should be used for actions, and <a> elements should be used for navigation.

Component API

PrimaryButton

Layout Component

PrimaryButton supports all props from thelayout component.

Props

Props extend from button. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
variant'inverse'

Variant has an option for inverse which will inverse the styling

iconPosition 'start' 'end'

Button icon positions can either be start or end. If no value is provided, it defaults to start.

'start'
fill

The fill color of the SystemIcon. This overrides color.

color

The color of the SystemIcon. This defines accent and fill. color may be overriden by accent and fill.

size

There are four button sizes: extraSmall, small, medium, and large. If no size is provided, it will default to medium.

styles
shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic

false
background

The background color of the SystemIcon.

cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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

The icon of the Button. Note: not displayed at small size

accent

The accent color of the SystemIcon. This overrides color.

accentHover

The accent color of the SystemIcon on hover. This overrides colorHover.

backgroundHover

The background color of the SystemIcon on hover.

colorHover

The hover color of the SystemIcon. This defines accentHover and fillHover. colorHover may be overriden by accentHover and fillHover.

fillHover

The fill color of the SystemIcon on hover. This overrides colorHover.

colors

Override default colors of a button. The default will depend on the button type

fillIconboolean

Whether the icon should received filled (colored background layer) or regular styles. Corresponds to toggled in ToolbarIconButton

shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic

false
growboolean

True if the component should grow to its container's width. False otherwise.

asReact.ElementType

Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using React.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

button
refReact.Ref<R = button>

Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If as is set to an element, it will be that element. If as is a component, the reference will be to that component (or element if the component uses React.forwardRef).

SecondaryButton

Layout Component

SecondaryButton supports all props from thelayout component.

Props

Props extend from button. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
variant'inverse'

Variant has an option for inverse which will inverse the styling

iconPosition 'start' 'end'

Button icon positions can either be start or end. If no value is provided, it defaults to start.

'start'
fill

The fill color of the SystemIcon. This overrides color.

color

The color of the SystemIcon. This defines accent and fill. color may be overriden by accent and fill.

size

There are four button sizes: extraSmall, small, medium, and large. If no size is provided, it will default to medium.

styles
shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic

false
background

The background color of the SystemIcon.

cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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

The icon of the Button. Note: not displayed at small size

accent

The accent color of the SystemIcon. This overrides color.

accentHover

The accent color of the SystemIcon on hover. This overrides colorHover.

backgroundHover

The background color of the SystemIcon on hover.

colorHover

The hover color of the SystemIcon. This defines accentHover and fillHover. colorHover may be overriden by accentHover and fillHover.

fillHover

The fill color of the SystemIcon on hover. This overrides colorHover.

colors

Override default colors of a button. The default will depend on the button type

fillIconboolean

Whether the icon should received filled (colored background layer) or regular styles. Corresponds to toggled in ToolbarIconButton

shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic

false
growboolean

True if the component should grow to its container's width. False otherwise.

asReact.ElementType

Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using React.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

button
refReact.Ref<R = button>

Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If as is set to an element, it will be that element. If as is a component, the reference will be to that component (or element if the component uses React.forwardRef).

TertiaryButton

Layout Component

TertiaryButton supports all props from thelayout component.

Props

Props extend from button. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
variant'inverse'

Variant has an option for inverse which will inverse the styling

isThemeableboolean
iconPosition 'start' 'end'

Button icon positions can either be start or end. If no value is provided, it defaults to start.

'start'
fill

The fill color of the SystemIcon. This overrides color.

color

The color of the SystemIcon. This defines accent and fill. color may be overriden by accent and fill.

size

There are four button sizes: extraSmall, small, medium, and large. If no size is provided, it will default to medium.

'medium'
styles
shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic

false
background

The background color of the SystemIcon.

cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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

The icon of the Button. Note: not displayed at small size

accent

The accent color of the SystemIcon. This overrides color.

accentHover

The accent color of the SystemIcon on hover. This overrides colorHover.

backgroundHover

The background color of the SystemIcon on hover.

colorHover

The hover color of the SystemIcon. This defines accentHover and fillHover. colorHover may be overriden by accentHover and fillHover.

fillHover

The fill color of the SystemIcon on hover. This overrides colorHover.

colors

Override default colors of a button. The default will depend on the button type

fillIconboolean

Whether the icon should received filled (colored background layer) or regular styles. Corresponds to toggled in ToolbarIconButton

shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic

false
growboolean

True if the component should grow to its container's width. False otherwise.

asReact.ElementType

Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using React.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

button
refReact.Ref<R = button>

Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If as is set to an element, it will be that element. If as is a component, the reference will be to that component (or element if the component uses React.forwardRef).

DeleteButton

Use sparingly for destructive actions that will result in data loss, can’t be undone, or will have significant consequences. They commonly appear in confirmation dialogs as the final confirmation before deleting.

Layout Component

DeleteButton supports all props from thelayout component.

Props

Props extend from button. Changing the as prop will change the element interface.

NameTypeDescriptionDefault
iconPosition 'start' 'end'

Button icon positions can either be start or end. If no value is provided, it defaults to start.

'start'
fill

The fill color of the SystemIcon. This overrides color.

color

The color of the SystemIcon. This defines accent and fill. color may be overriden by accent and fill.

size

There are four button sizes: extraSmall, small, medium, and large. If no size is provided, it will default to medium.

styles
shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic

false
background

The background color of the SystemIcon.

cs

The cs prop takes in a single value or an array of values. You can pass the CSS class name returned by , or the result of and . If you're extending a component already using cs, you can merge that prop in as well. Any style that is passed to the cs prop will override style props. If you wish to have styles that are overridden by the css prop, or styles added via the styled API, use wherever elemProps is used. If your component needs to also handle style props, use instead.

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

The icon of the Button. Note: not displayed at small size

accent

The accent color of the SystemIcon. This overrides color.

accentHover

The accent color of the SystemIcon on hover. This overrides colorHover.

backgroundHover

The background color of the SystemIcon on hover.

colorHover

The hover color of the SystemIcon. This defines accentHover and fillHover. colorHover may be overriden by accentHover and fillHover.

fillHover

The fill color of the SystemIcon on hover. This overrides colorHover.

colors

Override default colors of a button. The default will depend on the button type

fillIconboolean

Whether the icon should received filled (colored background layer) or regular styles. Corresponds to toggled in ToolbarIconButton

shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic

false
growboolean

True if the component should grow to its container's width. False otherwise.

asReact.ElementType

Optional override of the default element used by the component. Any valid tag or Component. If you provided a Component, this component should forward the ref using React.forwardRefand spread extra props to a root element.

Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care.

button
refReact.Ref<R = button>

Optional ref. If the component represents an element, this ref will be a reference to the real DOM element of the component. If as is set to an element, it will be that element. If as is a component, the reference will be to that component (or element if the component uses React.forwardRef).

Specifications

GivenWhenThen
given primary buttons are rendered
    • it should not have any axe errors
    given primary buttons are rendered
      • it should render the correct text
      given delete buttons are rendered
        • it should not have any axe errors
        given delete buttons are rendered
          • it should render the correct text
          Source: Button.spec.ts

          Accessibility Guidelines

          How Buttons Impact the Accessible Experience

          When buttons are disabled on the UI, color contrast guidelines do not apply to disabled components. Minimum contrast guidelines set in WCAG 2.1 explicitly state disabled components are exempt from the guideline.

          When identical buttons are used repeatedly on a screen, users must correctly identify the context around the buttons that cannot be distinguished from one another.

          • For example: Pencil icon buttons used repeatedly on a profile screen, each designed to edit a section of the profile. Providing uniquely descriptive names (e.g. “Edit photo”, “Edit contact info”) for each icon button can be valuable for screen reader users.

          When icons are used inside of buttons containing text, a text alternative is only necessary when the icon is communicating something about the button.

          • For example: A ‘+’ icon used in a skill pill named “communication” signals an action that is not expressed in the text.
          • On the other hand: An icon of an eye used to decorate a “View Details” button is redundant and should be hidden from screen readers.

          Keyboard Interaction

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

          Buttons should support the following keyboard interactions:

          • Tab: Focus on a button
          • Enter or Space: Activate the button

          Screen Reader Interaction

          Buttons should communicate the following to users:

          • The intended purpose, or function, of the Button
          • If applicable, the toggle state of the Button when it has 2 states
          • If applicable, an instruction that the Button will open a menu

          Design Annotations Needed

          • Write accessible name for icon-only button variants. Read more about non-text content.

          Implementation Markup Needed

          • An aria-label string is required for icon-only buttons and accessible tooltips can show the icon's name for everyone.
          • If the button has 2 toggle states, an aria-pressed attribute is required.
          • If the button has an attached menu, an aria-haspopup=”true” attribute is required.
          • [Included in component] Decorative <svg> icons are hidden from assistive technology with role=”presentation” and focusable=”false”.

          Content Guidelines

          • See the Buttons and Calls to Action page in the UI Text section of the Content Style Guide for button language guidelines.
          • When writing Tooltips to pair with icon-only variants, refer to the Tooltips 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