@workday/canvas-kit-react-button v4.8.1

Canvas Kit Button

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

Disclaimer

The documentation below is for the current Canvas buttons. The next iteration of our buttons have been implemented in this module, but will not be documented until we're ready to roll them out across all our products. We want to discourage their use until everyone can uptake them simultaneously for consistencies sake.

The new buttons include new ButtonTypes, icon support, and the ButtonSizes equate to different button and font sizes.

If you would like to use the new buttons, please consult the design systems team and get approval first

Installation

yarn add @workday/canvas-kit-react

or

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

Usage

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

<Button>Button Label</Button>;

Static Properties

Sizes: ButtonSizes

<Button buttonSize={Button.Sizes.Small}>Small Button</Button>

Types: ButtonTypes

<Button buttonType={Button.Types.Primary}>Primary Button</Button>

Component Props

Required

children: ReactNode

Buttons cannot be empty

Optional

buttonType: ButtonTypes

The type of the button

Default: ButtonTypes.Secondary

buttonSize: ButtonSizes

The type of the button

Default: ButtonSizes.Large

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 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 title="Activity Stream" aria-label="Activity Stream">
  <SystemIcon icon={activityStreamIcon} />
</IconButton>;

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

Static Properties

Sizes: ButtonSizes

<IconButton buttonSize={IconButton.Sizes.Small} icon={xIcon} />

Types: IconButtonTypes

<IconButton buttonType={IconButton.Types.Plain} icon={xIcon} />

Component Props

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

Optional

buttonType: IconButtonTypes

The type of the icon button

Default: IconButtonTypes.Circle

buttonSize: IconButton.Sizes.Small | IconButton.Sizes.Medium

The size of the icon button

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.

value: string

Value of the button. Must be unique if used within an IconButtonToggleGroup.

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.

Icon Button Toggle Group

Group of buttons containing an icon. This is a controlled component.

Usage

import * as React from 'react';
import {IconButton, IconButtonToggleGroup} from '@workday/canvas-kit-react-button';
import {listViewIcon, worksheetsIcon} from '@workday/canvas-system-icons-web';

<IconButtonToggleGroup>
  <IconButton icon={listViewIcon} value="list-view" title="List View" aria-label="List View" />
  <IconButton icon={worksheetsIcon} value="table-view" title="Worksheets" aria-label="Worksheets" />
</IconButtonToggleGroup>;

Note: while managing state using a unique value for each IconButton child is encouraged, you can also use indexes and omit the value field. It is strongly recommended to not mix these two methods.

Static Properties

None

Component Props

Required

children: React.ReactElement<IconButton>[]

Icon buttons to toggle between.

Optional

value: string | number

Identify which item is selected (toggled=true).
If a string is passed, the IconButton with the corresponding value will be selected.
If a number is passed, the IconButton with the corresponding index will be selected.

isRTL: boolean

Identify whether to render from right to left

onChange: (value:string | number)=> void

Callback function when a toggle button is selected. The value (if defined) or the index of the button will be returned.