Canvas Kit Button

Clickable button elements that extend the native <button> element with Canvas styling.

Installation

yarn add @workday/canvas-kit-react

or

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

Deprecation Warning

We are rolling out our next iteration of our buttons and will be deprecating the old style (orange primary, and accompanying secondary, and delete). These are still avialable, but will be removed in the first major release after they are available for all Workday customers. The biggest change is with regards to colors and styling, but the behavior should remain the same.

New Button

Anywhere you were using Button, you will automatically get the updated styling (previously beta_Button). This will be a visual breaking change (padding and colors have changed). The new buttons include: blue primary button, and accompanying secondary, delete, outline, highlight, and dropdown buttons. The import and usage is documented below.

Deprecated Buttons

If you need to continue to use the old style buttons, you can use the deprecated_Button class. Usage will be the same as before, but you must change your imports. Note: this will be removed entirely in a future release.

import * as React from 'react';
import {deprecated_Button as Button} from '@workday/canvas-kit-react-button';

<Button>Button Label</Button>;

Deprecation tags have been added to all the pieces regarding the old buttons including it's types and the component itself. Tslint and your IDE should reflect this warning but you should still be able to compile your code.

Table of Contents

• Button
• DeleteButton
• DropdownButton
• HighlightButton
• OutlineButton
• TextButton
• Icon Button

Button

import * as React from 'react';
import {Button} from '@workday/canvas-kit-react-button';

<Button>Button Label</Button>;

Static Properties

Size: 'small' | 'medium' | 'large'

<Button size={Button.Size.Small}>Small Button</Button>

Variant: ButtonVariant

<Button variant={Button.Variant.Primary}>Primary Button</Button>

Component Props

Required

children: ReactNode

Buttons cannot be empty

Optional

variant: ButtonVariant

The type of the button

Default: ButtonVariant.Secondary

| Theme | Description | | ----------- | ------------------------------- | | Primary | Blue background, white text | | Secondary | Gray background, dark gray text |

size: 'small' | 'medium' | 'large'

The size of the button

Default: 'medium'

| Theme | Description | | -------- | -------------------------------------- | | small | 24px tall, small padding, small text | | medium | 32px tall, medium padding, medium text | | large | 48px tall, large padding, larger text |

grow: boolean

If true, the button will grow to its container's width.

Default: false

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

dataLabel: String

The data label of the button (generally used for media timestamps).

Note: not displayed at small size.

icon: CanvasSystemIcon

The icon of the button.

Note: not displayed at small size.

DeleteButton

import * as React from 'react';
import {DeleteButton} from '@workday/canvas-kit-react-button';

<DeleteButton>Button Label</DeleteButton>;

Static Properties

Size: 'small' | 'medium' | 'large'

<DeleteButton size={DeleteButton.Size.Small}>Small Button</DeleteButton>

Component Props

Required

children: ReactNode

Buttons cannot be empty

Optional

size: 'small' | 'medium' | 'large'

The size of the button

Default: 'medium'

| Theme | Description | | -------- | -------------------------------------- | | small | 24px tall, small padding, small text | | medium | 32px tall, medium padding, medium text | | large | 48px tall, large padding, larger text |

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

grow: boolean

If true, the button will grow to its container's width.

Default: false

DropdownButton

import * as React from 'react';
import {DropdownButton} from '@workday/canvas-kit-react-button';

<DropdownButton>Button Label</DropdownButton>;

Static Properties

Size: 'medium' | 'large'

<DropdownButton size={DropdownButton.Size.Large}>Large Button</DropdownButton>

Variant: DropdownButtonVariant

<DropdownButton variant={DropdownButton.Variant.Primary}>Primary Button</DropdownButton>

Component Props

Required

children: ReactNode

Buttons cannot be empty

Optional

variant: ButtonVariant

The type of the button

Default: DropdownButtonVariant.Secondary

| Theme | Description | | ----------- | ------------------------------------ | | Primary | Blue background, white text/icon | | Secondary | Gray background, dark gray text/icon |

size: 'medium' | 'large'

The size of the button

Default: 'medium'

| Theme | Description | | -------- | -------------------------------------- | | medium | 32px tall, medium padding, medium text | | large | 48px tall, large padding, larger text |

grow: boolean

If true, the button will grow to its container's width.

Default: false

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

HighlightButton

import * as React from 'react';
import {HighlightButton} from '@workday/canvas-kit-react-button';

<HighlightButton>Button Label</HighlightButton>;

Static Properties

Size: 'medium' | 'large'

<HighlightButton size={HighlightButton.Size.Large}>Large Button</HighlightButton>

Component Props

Required

children: ReactNode

Buttons cannot be empty

Optional

size: 'medium' | 'large'

The size of the button

Default: 'medium'

| Theme | Description | | -------- | -------------------------------------- | | medium | 32px tall, medium padding, medium text | | large | 48px tall, large padding, larger text |

grow: boolean

If true, the button will grow to its container's width.

Default: false

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

icon: CanvasSystemIcon

The icon of the button

OutlineButton

import * as React from 'react';
import {OutlineButton} from '@workday/canvas-kit-react-button';

<OutlineButton>Button Label</OutlineButton>;

Static Properties

Size: 'small' | 'medium' | 'large'

<OutlineButton size={OutlineButton.Size.Small}>Small Button</OutlineButton>

Variant: OutlineButtonVariant

<OutlineButton variant={OutlineButton.Variant.Primary}>Primary Button</OutlineButton>

Component Props

Required

children: ReactNode

Buttons cannot be empty

Optional

variant: ButtonVariant

The type of the button

Default: OutlineButtonVariant.Secondary

| Theme | Description | | ----------- | --------------------------------------------- | | Primary | Transparent background, blue border and text | | Secondary | Transparent background, gray border and text | | Inverse | Transparent background, white border and text |

size: 'small' | 'medium' | 'large'

The size of the button

Default: 'medium'

| Theme | Description | | -------- | -------------------------------------- | | small | 24px tall, small padding, small text | | medium | 32px tall, medium padding, medium text | | large | 48px tall, large padding, larger text |

grow: boolean

If true, the button will grow to its container's width.

Default: false

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

dataLabel: String

The data label of the button (generally used for media timestamps)

Note: not displayed at small size.

icon: CanvasSystemIcon

The icon of the button

Note: not displayed at small size.

TextButton

import * as React from 'react';
import {TextButton} from '@workday/canvas-kit-react-button';

<TextButton>Button Label</TextButton>;

Static Properties

Size: 'small' | 'medium'

<TextButton size={TextButton.Size.Small}>Small Button</TextButton>

Variant: ButtonVariant

<TextButton variant={TextButton.Variant.Inverse}>Inverse Button</TextButton>

Component Props

Required

children: ReactNode

Buttons cannot be empty

Optional

variant: TextButtonVariant

The type of the button

Default: TextButtonVariant.Default

| Theme | Description | | --------- | ----------- | | Default | Blue text | | Inverse | White text |

size: 'small' | 'medium' | 'large'

The size of the button

Default: 'medium'

| Theme | Description | | -------- | -------------------------------------- | | small | 24px tall, small padding, small text | | medium | 32px tall, medium padding, medium text | | large | 48px tall, large padding, larger text |

iconPosition: ButtonIconPosition

The position of the TextButton icon.

Default: ButtonIconPosition.Left

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

icon: CanvasSystemIcon

The icon of the button.

allCaps: boolean

The capitialization of the text in the button.

Icon Button

Button containing an icon. Icon may be a component from canvas-kit-react-icon or an svg element.

Usage

import * as React from 'react';
import {IconButton} from '@workday/canvas-kit-react-button';
import {SystemIcon} from '@workday/canvas-kit-react-icon';
import {activityStreamIcon} from '@workday/canvas-system-icons-web';

<IconButton icon={activityStreamIcon} title="Activity Stream" aria-label="Activity Stream" />;

Static Properties

Size: 'small' | 'medium'

<IconButton size={IconButton.Size.Small} icon={xIcon} />

Variant: IconButtonVariant

<IconButton variant={IconButton.Variant.Plain} icon={xIcon} />

Component Props

Same as Button Undocumented props are spread to the button element.

Required

aria-label: string

The accessibility label to indicate the action triggered by clicking the icon button.

Optional

variant: IconButtonVariant

The type of the icon button

Default: IconButtonVariant.Circle

| Theme | Description | | --------------- | ------------------------------------------------ | | Square | Square, white background, dark gray icon | | SquareFilled | Square, gray background, dark gray icon | | Plain | Dark gray icon | | Circle | Circular, dark gray icon | | CircleFilled | Circular, gray background, dark gray icon | | Inverse | Circular, transparent background, white icon | | InverseFilled | Circular, semitransparent background, white icon |

size: 'small' | 'medium

The size of the icon button

Default: 'medium'

| Theme | Description | Is Default | | -------- | ----------------------------- | ---------- | | Small | 32px Diameter, 20px Icon Size | False | | Medium | 40px Diameter, 24px Icon Size | True |

toggled: boolean | undefined

If defined as a boolean, then it manages the button state: on (true) or off (false). This is a controlled button component. If left undefined then the button is not considered toggle-able (aria-pressed is undefined) and will act as a normal button.

Default: undefined

onToggleChange: (toggled: boolean | undefined) => void

The callback that is fired when a button toggle prop changes This is true when the toggle changes from true to false but also if you disable the toggle-ability of a button (in other words, if toggle changes from a boolean to undefined). This is important because the aria-pressed attribute for accessibility is goverened by whether or not the toggle prop is defined.

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

icon: CanvasSystemIcon

The icon of the button. Optional because IconButton can also wrap a SystemIcon component.

Accessibility Notes

The content of an IconButton is not always clear to the user. In order to better convey what the icon represents, the IconButton should be initialized with title and aria-label attributes.