Button

Buttons highlight actions available on a screen.

GitHubStorybook
yarn add @workday/canvas-kit-react
Sources
GitHubStorybook
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.
  • 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

  • Use Hyperlinks within a paragraph to navigate to another page. See the Button or Hyperlink section of the Buttons and Calls to Action pattern for more information and best practices.

Examples

PrimaryButton

Here is a basic example of a Primary Button. Buttons can be customized with several props to change the size, add an icon, etc.

Primary Buttons are high emphasis. Use once per screen to draw attention to the highest priority action. Multiple primary buttons make it confusing for the user to understand what action they should take. Not all screens require a Primary Button.

Primary Buttons have four sizes: extraSmall, small, medium, and large. Icons are supported for every size and can be positioned at the start or end with the iconPosition prop.

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.

Props

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

NameTypeDefaultDescription
variant"inverse" | undefinedundefinedThe variant of the PrimaryButton.
sizeButtonSizes | undefined'medium'There are four button sizes: `extraSmall`, `small`, `medium`, and `large`. If no size is provided, it will default to `medium`.
iconCanvasSystemIcon | undefinedThe icon of the Button. Note: not displayed at `small` size
iconPositionIconPositions | undefined'start'Button icon positions can either be `start` or `end`. If no value is provided, it defaults to `start`.
shouldMirrorIconboolean | undefinedfalseIf set to `true`, transform the icon's x-axis to mirror the graphic
themeEmotionCanvasTheme | undefined
growboolean | undefinedTrue if the component should grow to its container's width. False otherwise.
colorsButtonColors | undefined
fillIconboolean | undefinedWhether the icon should received filled (colored background layer) or regular styles. Corresponds to `toggled` in ToolbarIconButton
refReact.Ref<any>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`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>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.forwardRef` and spread extra props to a root element.

SecondaryButton

Secondary Buttons have a medium level of emphasis. Use them for non-critical actions. Secondary Buttons can be used on most pages without restrictions and work well for multiple actions of equal weight. They can be used in conjunction with a Primary Button or independently.

Secondary Buttons have four sizes: extraSmall, small, medium, and large. Icons are supported for every size and can be positioned at the start or end with the iconPosition prop.

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.

Props

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

NameTypeDefaultDescription
variant"inverse" | undefinedundefinedThe variant of the SecondaryButton.
sizeButtonSizes | undefined'medium'There are four button sizes: `extraSmall`, `small`, `medium`, and `large`. If no size is provided, it will default to `medium`.
iconCanvasSystemIcon | undefinedThe icon of the Button. Note: not displayed at `small` size
iconPositionIconPositions | undefined'start'Button icon positions can either be `start` or `end`. If no value is provided, it defaults to `start`.
shouldMirrorIconboolean | undefinedfalseIf set to `true`, transform the icon's x-axis to mirror the graphic
themeEmotionCanvasTheme | undefined
growboolean | undefinedTrue if the component should grow to its container's width. False otherwise.
colorsButtonColors | undefined
fillIconboolean | undefinedWhether the icon should received filled (colored background layer) or regular styles. Corresponds to `toggled` in ToolbarIconButton
refReact.Ref<any>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`).
as"symbol" | "object" | "small" | "a" | "abbr" | "address" | "area" | "article" | "aside" | "audio" | "b" | "base" | "bdi" | "bdo" | "big" | "blockquote" | "body" | "br" | "button" | ... 156 more ... | React.ComponentType<any>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.forwardRef` and spread extra props to a root element.

TertiaryButton

Tertiary Buttons have the lowest emphasis. Use for less important actions that the user may not often be looking to do. Tertiary Buttons have lower prominence as its container is not visible until it is interacted with. Use Tertiary Buttons for supplemental actions such as “View More”, “Read More” or “Select a File”. Tertiary Buttons are frequently used on Cards.

Tertiary Buttons have three sizes: extraSmall, small, medium and large. Icons are supported for every size and can be positioned at the start or end with the iconPosition prop.

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.