@workday/canvas-kit-react-button

Canvas Kit Button

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

> Workday Design Reference

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
• Hyperlink
• IconButton
• ToolbarIconButton
• ToolbarDropdownButton

---

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.

---

as: 'a'

The alternative container type for the button. If as="a" is provided, We use Emotion's special as prop to render an a tag instead of a button.

When defined, all props available via React.AnchorHTMLAttributes<HTMLAnchorElement> (e.g. href, target, etc.) become available.

Default: undefined

---

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

---

as: 'a'

The alternative container type for the button. If as="a" is provided, We use Emotion's special as prop to render an a tag instead of a button.

When defined, all props available via React.AnchorHTMLAttributes<HTMLAnchorElement> (e.g. href, target, etc.) become available.

Default: undefined

---

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.

---

as: 'a'

The alternative container type for the button. If as="a" is provided, We use Emotion's special as prop to render an a tag instead of a button.

When defined, all props available via React.AnchorHTMLAttributes<HTMLAnchorElement> (e.g. href, target, etc.) become available.

Default: undefined

---

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

---

as: 'a'

The alternative container type for the button. If as="a" is provided, We use Emotion's special as prop to render an a tag instead of a button.

When defined, all props available via React.AnchorHTMLAttributes<HTMLAnchorElement> (e.g. href, target, etc.) become available.

Default: undefined

---

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.

---

as: 'a'

The alternative container type for the button. If as="a" is provided, We use Emotion's special as prop to render an a tag instead of a button.

When defined, all props available via React.AnchorHTMLAttributes<HTMLAnchorElement> (e.g. href, target, etc.) become available.

Default: undefined

---

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.

---

as: 'a'

The alternative container type for the button. If as="a" is provided, We use Emotion's special as prop to render an a tag instead of a button.

When defined, all props available via React.AnchorHTMLAttributes<HTMLAnchorElement> (e.g. href, target, etc.) become available.

Default: undefined

---

Hyperlink

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

<Hyperlink href={url}>Link</Hyperlink>;

Hyperlink will apply our link styling, but follow the font styles of it's container (size, weight, line-height, etc.).

Static Properties

Variant: ButtonVariant

<Hyperlink variant={Hyperlink.Variant.Inverse}>Link</Hyperlink>

The style of the link for different backgrounds

Default: TextButtonVariant.Default

Theme	Description
Default	Blue text
Inverse	White text

Component Props

Required

None

Optional

href: string

The href url of the anchor tag

---

IconButton

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

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.

---

as: 'a'

The alternative container type for the button. If as="a" is provided, We use Emotion's special as prop to render an a tag instead of a button.

When defined, all props available via React.AnchorHTMLAttributes<HTMLAnchorElement> (e.g. href, target, etc.) become available.

Default: undefined

---

ToolbarIconButton

Button containing an icon. Icon may be a component from canvas-kit-react-icon or an svg element. Note: This button is intended to be used within a toolbar.

Usage

import * as React from 'react';
import {ToolbarIconButton} from '@workday/canvas-kit-react-button';
import {activityStreamIcon} from '@workday/canvas-system-icons-web';
<ToolbarIconButton icon={activityStreamIcon} aria-label="Activity Stream" />;

Static Properties

None

Component Props

Required

aria-label: string

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

---

Optional

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 ToolbarIconButton can also wrap a SystemIcon component.

---

ToolbarDropdownButton

Button containing an icon or custom element. Icon may be a component from canvas-kit-react-icon or an svg element. By default, the button has a down chevron to the right indicating that it's a dropdown button. Note: This button is intended to be used within a toolbar.

Usage

import * as React from 'react';
import {ToolbarDropdownButton} from '@workday/canvas-kit-react-button';
import {activityStreamIcon} from '@workday/canvas-system-icons-web';
<ToolbarDropdownButton icon={activityStreamIcon} aria-label="Activity Stream" />;

Static Properties

None

Component Props

Required

aria-label: string

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

---

Optional

buttonRef: React.Ref<HTMLButtonElement>

Returns the ref to the rendered HTMLButtonElement.

---

icon: CanvasSystemIcon

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

---