Skip to Content

Button

Buttons highlight actions available on a screen.

Interaction Modes

Reviewing

Selecting

Install

yarn add @workday/canvas-kit-react

Component Type

Button

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.2.12

Experience Surfaces

Page Body Inline

Component Type

Button

Platform

Web

Component

Sana Canvas

Delivery Channels

Web

Version

16.2.12

Experience Surfaces

Page Body Inline

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

  • Use Hyperlinks within a paragraph to navigate to another page.
  • Consider using checkbox, switch, or segmented control when a component is needed that can capture 2 togglable states.

Design Annotations for Accessibility

  • Write accessible name for icon-only button variants.

Examples

PrimaryButton

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

import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {
  caretDownIcon,
  plusIcon,
  relatedActionsVerticalIcon,
} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  padding: system.padding.md,
});

export default () => (
  <Flex cs={parentContainerStyles}>
    <PrimaryButton>Primary</PrimaryButton>
    <PrimaryButton icon={plusIcon} iconPosition="start">
      Primary
    </PrimaryButton>
    <PrimaryButton icon={caretDownIcon} iconPosition="end">
      Primary
    </PrimaryButton>
    <Tooltip title="Related Actions">
      <PrimaryButton icon={relatedActionsVerticalIcon} />
    </Tooltip>
  </Flex>
);

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 neutral400.

import React from 'react';

import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {
  caretDownIcon,
  plusIcon,
  relatedActionsVerticalIcon,
} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  backgroundColor: system.color.surface.contrast.default,
  padding: system.padding.md,
});

export default () => (
  <Flex cs={parentContainerStyles}>
    <PrimaryButton variant="inverse">Primary</PrimaryButton>
    <PrimaryButton icon={plusIcon} iconPosition="start" variant="inverse">
      Primary
    </PrimaryButton>
    <PrimaryButton icon={caretDownIcon} iconPosition="end" variant="inverse">
      Primary
    </PrimaryButton>
    <Tooltip title="Related Actions">
      <PrimaryButton icon={relatedActionsVerticalIcon} variant="inverse" />
    </Tooltip>
  </Flex>
);

SecondaryButton

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

import React from 'react';

import {SecondaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {
  caretDownIcon,
  plusIcon,
  relatedActionsVerticalIcon,
} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  padding: system.padding.md,
});

export default () => (
  <Flex cs={parentContainerStyles}>
    <SecondaryButton>Secondary</SecondaryButton>
    <SecondaryButton icon={plusIcon} iconPosition="start">
      Secondary
    </SecondaryButton>
    <SecondaryButton icon={caretDownIcon} iconPosition="end">
      Secondary
    </SecondaryButton>
    <Tooltip title="Related Actions">
      <SecondaryButton icon={relatedActionsVerticalIcon} />
    </Tooltip>
  </Flex>
);

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 neutral400.

import React from 'react';

import {SecondaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {
  caretDownIcon,
  plusIcon,
  relatedActionsVerticalIcon,
} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  padding: system.padding.md,
  backgroundColor: system.color.surface.contrast.default,
});

export default () => (
  <Flex cs={parentContainerStyles}>
    <SecondaryButton variant="inverse">Secondary</SecondaryButton>
    <SecondaryButton icon={plusIcon} variant="inverse">
      Secondary
    </SecondaryButton>
    <SecondaryButton icon={caretDownIcon} variant="inverse" iconPosition="end">
      Secondary
    </SecondaryButton>
    <Tooltip title="Related Actions">
      <SecondaryButton icon={relatedActionsVerticalIcon} variant="inverse" />
    </Tooltip>
  </Flex>
);

TertiaryButton

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

import React from 'react';

import {TertiaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {
  caretDownIcon,
  plusIcon,
  relatedActionsVerticalIcon,
} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  padding: system.padding.md,
});

export default () => (
  <Flex cs={parentContainerStyles}>
    <TertiaryButton>Tertiary</TertiaryButton>
    <TertiaryButton icon={plusIcon} iconPosition="start">
      Tertiary
    </TertiaryButton>
    <TertiaryButton icon={caretDownIcon} iconPosition="end">
      Tertiary
    </TertiaryButton>
    <Tooltip title="Related Actions">
      <TertiaryButton icon={relatedActionsVerticalIcon} />
    </Tooltip>
  </Flex>
);

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 neutral400.

import React from 'react';

import {TertiaryButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {
  caretDownIcon,
  plusIcon,
  relatedActionsVerticalIcon,
} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  padding: system.padding.md,
  backgroundColor: system.color.surface.contrast.default,
});

export default () => (
  <Flex cs={parentContainerStyles}>
    <TertiaryButton variant="inverse">Tertiary</TertiaryButton>
    <TertiaryButton icon={plusIcon} iconPosition="start" variant="inverse">
      Tertiary
    </TertiaryButton>
    <TertiaryButton icon={caretDownIcon} iconPosition="end" variant="inverse">
      Tertiary
    </TertiaryButton>
    <Tooltip title="Related Actions">
      <TertiaryButton icon={relatedActionsVerticalIcon} variant="inverse" />
    </Tooltip>
  </Flex>
);

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 being deleted.

import {DeleteButton} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {trashIcon} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  padding: system.padding.md,
});

export default () => (
  <Flex cs={parentContainerStyles}>
    <DeleteButton>Delete</DeleteButton>
    <DeleteButton icon={trashIcon} iconPosition="start">
      Delete
    </DeleteButton>
    <DeleteButton icon={trashIcon} iconPosition="end">
      Delete
    </DeleteButton>
    <Tooltip title="Delete">
      <DeleteButton icon={trashIcon} />
    </Tooltip>
  </Flex>
);

Delete Buttons also have an outline variant.

import {DeleteButton} from '@workday/canvas-kit-react/button';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {trashIcon} from '@workday/canvas-system-icons-web';
import {system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  display: 'flex',
  gap: system.gap.md,
  padding: system.padding.md,
});

export default () => (
  <div className={parentContainerStyles}>
    <DeleteButton variant="outline">Delete</DeleteButton>
    <DeleteButton icon={trashIcon} iconPosition="start" variant="outline">
      Delete
    </DeleteButton>
    <DeleteButton icon={trashIcon} iconPosition="end" variant="outline">
      Delete
    </DeleteButton>
    <Tooltip title="Delete">
      <DeleteButton icon={trashIcon} variant="outline" />
    </Tooltip>
  </div>
);

Grow Prop

The example below shows the use of the grow prop on different variants of buttons. This will set the width of the button to the width of its container.

import {
  DeleteButton,
  PrimaryButton,
  SecondaryButton,
  TertiaryButton,
} from '@workday/canvas-kit-react/button';
import {Flex} from '@workday/canvas-kit-react/layout';
import {px2rem} from '@workday/canvas-kit-styling';
import {system} from '@workday/canvas-tokens-web';

const baseStyles = {
  gap: system.gap.md,
  padding: system.padding.md,
  flexDirection: 'column',
  maxWidth: px2rem(300),
};

export default () => (
  <Flex cs={baseStyles}>
    <PrimaryButton size="small" grow={true}>
      Primary
    </PrimaryButton>
    <SecondaryButton size="small" grow={true}>
      Secondary
    </SecondaryButton>
    <TertiaryButton size="small" grow={true}>
      Tertiary
    </TertiaryButton>
    <DeleteButton size="small" grow={true}>
      Delete
    </DeleteButton>
  </Flex>
);

Custom Styles

All of our buttons support custom styling via the cs prop. For more information, check our “How To Customize Styles”  or view the example below.

import {PrimaryButton, PrimaryButtonProps, buttonStencil} from '@workday/canvas-kit-react/button';
import {createComponent} from '@workday/canvas-kit-react/common';
import {systemIconStencil} from '@workday/canvas-kit-react/icon';
import {Grid} from '@workday/canvas-kit-react/layout';
import {createStencil, createStyles, px2rem} from '@workday/canvas-kit-styling';
import {plusIcon} from '@workday/canvas-system-icons-web';
import {base, system} from '@workday/canvas-tokens-web';

const customContainer = createStyles({
  gap: system.gap.md,
  maxWidth: 'max-content',
});

const myButtonStencil = createStencil({
  base: {
    [buttonStencil.vars.background]: base.green100,
    [buttonStencil.vars.label]: base.green700,
    [systemIconStencil.vars.color]: base.green700,
    [buttonStencil.vars.borderRadius]: px2rem(2),
    border: `${px2rem(3)} solid transparent`,
    '&:focus-visible': {
      [buttonStencil.vars.background]: base.green700,
      [buttonStencil.vars.boxShadowInner]: base.green100,
      [buttonStencil.vars.boxShadowOuter]: base.green700,
      [systemIconStencil.vars.color]: system.color.fg.inverse,
    },
    '&:hover': {
      [buttonStencil.vars.background]: base.green600,
      border: `${px2rem(3)} dotted ${base.green700}`,
      [buttonStencil.vars.label]: base.green700,
      [systemIconStencil.vars.color]: system.color.fg.inverse,
    },
    '&:active': {
      [buttonStencil.vars.background]: base.green700,
      [buttonStencil.vars.label]: system.color.fg.inverse,
      [systemIconStencil.vars.color]: system.color.fg.inverse,
    },
  },
});

const MyCustomButton = createComponent('button')({
  Component: ({children, cs, ...elemProps}: PrimaryButtonProps, ref, Element) => (
    <PrimaryButton as={Element} ref={ref} cs={[myButtonStencil(), cs]} {...elemProps}>
      {children}
    </PrimaryButton>
  ),
});

const myCustomStyles = createStyles({
  padding: system.padding.md,
  textTransform: 'uppercase',
  [buttonStencil.vars.background]: base.slate200,
  [buttonStencil.vars.label]: base.slate700,
  [systemIconStencil.vars.color]: base.slate700,
  [buttonStencil.vars.borderRadius]: system.shape.md,
  [buttonStencil.vars.border]: base.slate800,
  '&:focus-visible': {
    [buttonStencil.vars.background]: base.slate700,
    [buttonStencil.vars.boxShadowInner]: base.slate200,
    [buttonStencil.vars.boxShadowOuter]: base.slate700,
    [systemIconStencil.vars.color]: system.color.fg.inverse,
  },
  '&:hover': {
    [buttonStencil.vars.background]: base.slate600,
    [buttonStencil.vars.border]: `${px2rem(3)} dotted ${base.slate700}`,
    [buttonStencil.vars.label]: base.slate700,
    [systemIconStencil.vars.color]: system.color.fg.inverse,
    border: `${px2rem(3)} dotted ${base.slate700}`,
  },
  '&:active': {
    [buttonStencil.vars.background]: base.slate700,
    [buttonStencil.vars.label]: system.color.fg.inverse,
    [systemIconStencil.vars.color]: system.color.fg.inverse,
  },
});

const customColors = {
  default: {
    background: base.amber100,
    icon: base.amber500,
    label: base.amber500,
  },
  focus: {
    background: base.amber500,
    boxShadowInner: base.amber100,
    boxShadowOuter: base.amber500,
  },
  hover: {
    background: base.amber400,
    icon: system.color.fg.inverse,
  },
  active: {
    background: base.amber500,
  },
  disabled: {},
};

export default () => (
  <Grid cs={customContainer}>
    <MyCustomButton icon={plusIcon}>Styling Override Via Stencil Variables</MyCustomButton>
    <MyCustomButton icon={plusIcon} cs={myCustomStyles}>
      Style Override Via Create Styles
    </MyCustomButton>
    <PrimaryButton icon={plusIcon} colors={customColors}>
      Styling Override Via Colors Prop
    </PrimaryButton>
  </Grid>
);

Theme Overrides

The most common way to theme our buttons is to pass a theme object at the root level of the application via the CanvasProvider. In the example below, our buttons use our brand.action.** tokens with the fallback being brand.primary.**.

Caution: Setting --cnvs-brand-action** tokens at the :root CSS will override all PrimaryButton theme colors set at the CanvasProvider level.

Note: You should not individually theme components wrapping them with the CanvasProvider, but rather theme at the root level of the application.

Override Primary Color Via Canvas Provider

Override Action Color Via CSS Action Token

import React from 'react';

import {PrimaryButton} from '@workday/canvas-kit-react/button';
import {CanvasProvider} from '@workday/canvas-kit-react/common';
import {Flex} from '@workday/canvas-kit-react/layout';
import {Heading} from '@workday/canvas-kit-react/text';
import {Tooltip} from '@workday/canvas-kit-react/tooltip';
import {createStyles} from '@workday/canvas-kit-styling';
import {
  caretDownIcon,
  plusIcon,
  relatedActionsVerticalIcon,
} from '@workday/canvas-system-icons-web';
import {brand, system} from '@workday/canvas-tokens-web';

const parentContainerStyles = createStyles({
  gap: system.gap.md,
  padding: system.padding.md,
});

const customActionTheme = createStyles({
  [brand.action.base]: 'teal',
  [brand.action.accent]: 'white',
  [brand.action.dark]: 'hsla(180, 100%, 20%)',
  [brand.action.darkest]: 'hsla(180, 100%, 16%)',
});

export default () => (
  <div>
    <Heading size="medium" as="h3">
      Override Primary Color Via Canvas Provider
    </Heading>
    <CanvasProvider
      theme={{
        canvas: {
          palette: {
            primary: {
              main: 'navy',
            },
          },
        },
      }}
    >
      <Flex cs={parentContainerStyles}>
        <PrimaryButton>Primary</PrimaryButton>
        <PrimaryButton icon={plusIcon} iconPosition="start">
          Primary
        </PrimaryButton>
        <PrimaryButton icon={caretDownIcon} iconPosition="end">
          Primary
        </PrimaryButton>
        <Tooltip title="Related Actions">
          <PrimaryButton icon={relatedActionsVerticalIcon} />
        </Tooltip>
      </Flex>
    </CanvasProvider>
    <Heading size="medium" as="h3">
      Override Action Color Via CSS Action Token
    </Heading>
    <div className={customActionTheme}>
      <Flex cs={parentContainerStyles}>
        <PrimaryButton>Primary</PrimaryButton>
        <PrimaryButton icon={plusIcon} iconPosition="start">
          Primary
        </PrimaryButton>
        <PrimaryButton icon={caretDownIcon} iconPosition="end">
          Primary
        </PrimaryButton>
        <Tooltip title="Related Actions">
          <PrimaryButton icon={relatedActionsVerticalIcon} />
        </Tooltip>
      </Flex>
    </div>
  </div>
);

Accessibility

The primary accessibility goal is a visible, programmatically determinable name on a native control that performs an in-page action (submit, open, dismiss, and similar). This page covers PrimaryButton, SecondaryButton, TertiaryButton, and DeleteButton.

Use Hyperlink when the control navigates to another URL or in-page location.

For Toolbar icon and dropdown controls, see that component’s documentation. For a control that opens a menu, dialog, or expandable, see Menu accessibility, Dialog accessibility, and Expandable accessibility.

When users choose one value from two or more mutually exclusive options, use Segmented Control—not a lone variant button. Use Radio when the selection needs radio semantics or native form submission.

See the Button pattern (APG)  and Canvas Kit Accessibility overview.

Minimum Accessible Structure

The following matches the PrimaryButton examples: visible text for the default case, text plus a decorative icon, and an icon-only control with an accessible name.

import {PrimaryButton} from '@workday/canvas-kit-react/button'; import {Tooltip} from '@workday/canvas-kit-react/tooltip'; import {plusIcon, relatedActionsVerticalIcon} from '@workday/canvas-system-icons-web'; <PrimaryButton>Save</PrimaryButton>; <PrimaryButton icon={plusIcon}>Add item</PrimaryButton>; <Tooltip title="Related Actions"> <PrimaryButton icon={relatedActionsVerticalIcon} /> </Tooltip>;

For icon-only buttons, prefer Tooltip with title and default type="label" (which sets aria-label from title so sighted users also see the label). Tooltip with type="label" overwrites the wrapped control’s accessible name—use it on icon-only buttons only; visible button text already supplies the name. If the spec explicitly says not to use a tooltip, set aria-label on the button instead. The same patterns apply to SecondaryButton, TertiaryButton, and DeleteButton.

Built-in Behaviors

Canvas Kit applies these automatically on PrimaryButton, SecondaryButton, TertiaryButton, and DeleteButton. Do not duplicate them in consuming code.

ARIA and DOM (applied by button components):

  • Variant buttons: Render a native <button> (via BaseButton) with default type="button". A passed type prop overrides that default—use type="submit" only when the button submits its form.
  • Visible label: Button text is rendered in BaseButton.Label (<span>) inside the <button> so its text contributes to the accessible name.
  • icon: Renders BaseButton.Icon (SystemIcon). Canvas Kit icon SVG markup uses role="presentation" and focusable="false", so icons beside visible text are not announced separately.
  • disabled: Maps to the native disabled attribute; disabled buttons are skipped in the tab order.
  • Focus: Visible focus styling uses :focus-visible.
  • ref: Forwards to the underlying <button>.
  • Native button attributes: Standard props (for example aria-label, aria-pressed, aria-expanded, id, onClick) pass through to the <button> unless you change the element with as. Variant buttons do not set aria-pressed unless you pass it for a deliberate toggle design.
  • Popup triggers: Variant buttons do not set aria-haspopup or aria-expanded. Menu.Target, Expandable.Target, and Dialog.Target own those per their docs.

Keyboard (native <button> behavior):

Variant buttons use native button keyboard support: Tab / Shift+Tab for focus order, and Enter or Space to activate.

Screen reader expectations (when built-in behaviors are used as intended):

  • On focus, assistive technology announces the button name (visible text and/or aria-label) and role (for example, “Save, button”).
  • Icons rendered with icon next to visible text are not announced as separate images.
  • Disabled buttons are announced as unavailable and are not in the tab order.
  • When a variant button has aria-pressed and a stable visible label, assistive technology announces the name, “toggle button,” and pressed or not pressed (for example, “Bold, toggle button, pressed”).
  • When a variant button is a popup *.Target, assistive technology follows that component’s documented popup and expanded behavior.

Accessibility Requirements

Required in application code for an accessible button. Rows marked (conditional) apply only when the situation matches—otherwise omit.

If no design spec is provided: use PrimaryButton with non-empty visible text and default type="button". Omit icon, disabled, Tooltip, aria-label, custom id, as, type="submit", and a ref unless the spec requires them.

RequirementHow to satisfy
Accessible nameNon-empty visible text inside the variant button
Icon-only name (conditional)Tooltip with type="label" and title on icon-only buttons (see PrimaryButton), or aria-label when the spec explicitly says not to use a tooltip
Variant choicePrimaryButton, SecondaryButton, TertiaryButton, or DeleteButton per design; DeleteButton only for destructive actions
Decorative icon (conditional)icon with visible text—meaning comes from button text
Form submit (conditional)type="submit" on the variant button inside a form that should submit when activated; omit type="submit" otherwise (default type="button")
Mutually exclusive group (conditional)Segmented Control for two or more in-page mutually exclusive options—not a single variant button or lone on/off control; use Radio when the selection is a form value
Toggle pressed state (conditional)On/off controls: use aria-pressed only when the visible label stays stable while state changes (not Mute/Unmute-style labels); set aria-pressed in both states and include or ask the user for visual styling for pressed state—variant buttons do not provide default pressed visuals. Omit for one-shot actions (Save, Delete, Open). For a toolbar toggle, use ToolbarIconButton—see Toolbar
Menu trigger (conditional)Compose Menu with Menu.Target as={PrimaryButton} (Menu.Target defaults to SecondaryButton). Context menus: Menu.ContextTarget. See Menu accessibility and Menu trigger composition below
Related button groups (conditional)Semantic grouping (<ul> / <li> or <fieldset> / <legend>) when several buttons share one question or legend; each control still needs its own accessible name
Disabled (conditional)Native disabled on the variant button when the spec marks the action unavailable
Navigation (conditional)Hyperlink instead of a variant button when the action is navigation
Programmatic focus (conditional)ref on the variant button and focus() only when the product must move focus after an action—omit by default

Menu trigger composition (conditional):

Menu.Target renders the trigger—do not nest a variant button inside it. Use as for a different variant. Add Menu.Popper, Menu.Card, and Menu.List per Menu accessibility.

import {PrimaryButton} from '@workday/canvas-kit-react/button'; import {Menu} from '@workday/canvas-kit-react/menu'; <Menu> <Menu.Target as={PrimaryButton}>Open</Menu.Target> {/* Menu.Popper, Menu.Card, Menu.List — see Menu accessibility */} </Menu>;

Summary for code generation:

  • REQUIRED: variant button with a non-empty accessible name (visible text for text buttons; for icon-only, Tooltip with type="label" preferred, or aria-label when the spec says not to use a tooltip)
  • CONDITIONAL: icon; icon-only naming; disabled; type="submit"; Menu composition with Menu.Target as={…}; ToolbarIconButton / aria-pressed per toggle row; Hyperlink for navigation; grouping markup; programmatic focus via ref

Anti-Patterns

Do not generate code that does the following (see Accessibility Requirements above for what to supply instead):

  • Use a <div>, <span>, role="button", or other non-<button> with onClick, or suppress Enter / Space on a control that should act as a button—use PrimaryButton, SecondaryButton, TertiaryButton, or DeleteButton for native keyboard and assistive technology behavior
  • Use a variant button when the action is URL navigation—use Hyperlink
  • Leave icon-only buttons unnamed, rely on the icon alone, use Tooltip with type="muted", or use aria-label when the spec allows Tooltip with type="label"—see Icon-only name
  • Nest a variant button inside Menu.Target, or hand-set aria-haspopup or aria-expanded when Menu.Target, Expandable.Target, or Dialog.Target owns that state—use Menu.Target as={…} (and the matching popup docs) instead
  • Set aria-pressed on one-shot actions (Save, Delete, Open) or on buttons whose visible label changes with state (for example Mute/Unmute)—see Toggle pressed state
  • Use SegmentedControl for a single option or a lone on/off control—see Mutually exclusive group
  • Use aria-disabled instead of native disabled on variant buttons

Component API

PrimaryButton

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'
shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the icon should mirror only when in an right-to-left language, use shouldMirrorIconInRTL instead.

false
shouldMirrorIconInRTLboolean

If set to true, transform the icon's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
colorstring

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

backgroundstring

The background color of the SystemIcon.

size

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

icon

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

shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the SVG should mirror only when in an right-to-left language, use shouldMirrorInRTL instead.

false
shouldMirrorInRTLboolean

If set to true, transform the SVG's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
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
colors

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

accentstring

The accent color of the SystemIcon. This overrides color.

fillIconboolean

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

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

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'
shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the icon should mirror only when in an right-to-left language, use shouldMirrorIconInRTL instead.

false
shouldMirrorIconInRTLboolean

If set to true, transform the icon's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
colorstring

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

backgroundstring

The background color of the SystemIcon.

size

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

icon

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

shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the SVG should mirror only when in an right-to-left language, use shouldMirrorInRTL instead.

false
shouldMirrorInRTLboolean

If set to true, transform the SVG's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
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
colors

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

accentstring

The accent color of the SystemIcon. This overrides color.

fillIconboolean

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

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

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'
shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the icon should mirror only when in an right-to-left language, use shouldMirrorIconInRTL instead.

false
shouldMirrorIconInRTLboolean

If set to true, transform the icon's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
colorstring

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

backgroundstring

The background color of the SystemIcon.

size

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

'medium'
icon

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

shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the SVG should mirror only when in an right-to-left language, use shouldMirrorInRTL instead.

false
shouldMirrorInRTLboolean

If set to true, transform the SVG's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
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
colors

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

accentstring

The accent color of the SystemIcon. This overrides color.

fillIconboolean

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

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 being deleted.

Props

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

NameTypeDescriptionDefault
variant'outline'

Variant has an option for outline which will reverse the styling of the button

iconPosition 'start' | 'end'

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

'start'
shouldMirrorIconboolean

If set to true, transform the icon's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the icon should mirror only when in an right-to-left language, use shouldMirrorIconInRTL instead.

false
shouldMirrorIconInRTLboolean

If set to true, transform the icon's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
colorstring

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

backgroundstring

The background color of the SystemIcon.

size

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

icon

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

shouldMirrorboolean

If set to true, transform the SVG's x-axis to mirror the graphic. Use this if you want to always mirror the icon regardless of the content direction. If the SVG should mirror only when in an right-to-left language, use shouldMirrorInRTL instead.

false
shouldMirrorInRTLboolean

If set to true, transform the SVG's x-axis to mirror the graphic when the content direction is rtl. Icons don't have enough context to know if they should be mirrored in all cases. Setting this to true indicates the icon should be mirrored in right-to-left languages.

false
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
colors

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

accentstring

The accent color of the SystemIcon. This overrides color.

fillIconboolean

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

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