Button
Buttons highlight actions available on a screen.
Component Type
Button
Platform
Web
Component
Sana Canvas
Delivery Channels
Web
Version
16.2.12Experience Surfaces
Page Body Inline
Anatomy

- Container (Conditional): Houses the contents of the Button. Visual appearance differs based on button type.
- Label (Conditional): Specific text describing the action.
- 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:rootCSS will override allPrimaryButtontheme colors set at theCanvasProviderlevel.
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>(viaBaseButton) with defaulttype="button". A passedtypeprop overrides that default—usetype="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: RendersBaseButton.Icon(SystemIcon). Canvas Kit icon SVG markup usesrole="presentation"andfocusable="false", so icons beside visible text are not announced separately.disabled: Maps to the nativedisabledattribute; 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 withas. Variant buttons do not setaria-pressedunless you pass it for a deliberate toggle design. - Popup triggers: Variant buttons do not set
aria-haspopuporaria-expanded.Menu.Target,Expandable.Target, andDialog.Targetown 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
iconnext 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-pressedand 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.
| Requirement | How to satisfy |
|---|---|
| Accessible name | Non-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 choice | PrimaryButton, 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,
Tooltipwithtype="label"preferred, oraria-labelwhen the spec says not to use a tooltip) - CONDITIONAL:
icon; icon-only naming;disabled;type="submit";Menucomposition withMenu.Target as={…};ToolbarIconButton/aria-pressedper toggle row;Hyperlinkfor navigation; grouping markup; programmatic focus viaref
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>withonClick, or suppress Enter / Space on a control that should act as a button—usePrimaryButton,SecondaryButton,TertiaryButton, orDeleteButtonfor 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
Tooltipwithtype="muted", or usearia-labelwhen the spec allowsTooltipwithtype="label"—see Icon-only name - Nest a variant button inside
Menu.Target, or hand-setaria-haspopuporaria-expandedwhenMenu.Target,Expandable.Target, orDialog.Targetowns that state—useMenu.Target as={…}(and the matching popup docs) instead - Set
aria-pressedon one-shot actions (Save, Delete, Open) or on buttons whose visible label changes with state (for example Mute/Unmute)—see Toggle pressed state - Use
SegmentedControlfor a single option or a lone on/off control—see Mutually exclusive group - Use
aria-disabledinstead of nativedisabledon variant buttons
Component API
PrimaryButton
Props
Props extend from button. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
variant | 'inverse' | Variant has an option for | |
iconPosition | 'start' | 'end' | Button icon positions can either be | 'start' |
shouldMirrorIcon | boolean | If set to | false |
shouldMirrorIconInRTL | boolean | If set to | false |
color | string | The color of the SystemIcon. This defines | |
background | string | The background color of the SystemIcon. | |
size | | There are four button sizes: | |
icon | | The icon of the Button.
Note: Not displayed at | |
shouldMirror | boolean | If set to | false |
shouldMirrorInRTL | boolean | If set to | false |
cs | | The | |
children | ReactNode | ||
colors | | Override default colors of a button. The default will depend on the button type | |
accent | string | The accent color of the SystemIcon. This overrides | |
fillIcon | boolean | Whether the icon should received filled (colored background layer) or regular styles.
Corresponds to | |
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
as | React.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 Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | button |
ref | React.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 |
SecondaryButton
Props
Props extend from button. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
variant | 'inverse' | Variant has an option for | |
iconPosition | 'start' | 'end' | Button icon positions can either be | 'start' |
shouldMirrorIcon | boolean | If set to | false |
shouldMirrorIconInRTL | boolean | If set to | false |
color | string | The color of the SystemIcon. This defines | |
background | string | The background color of the SystemIcon. | |
size | | There are four button sizes: | |
icon | | The icon of the Button.
Note: Not displayed at | |
shouldMirror | boolean | If set to | false |
shouldMirrorInRTL | boolean | If set to | false |
cs | | The | |
children | ReactNode | ||
colors | | Override default colors of a button. The default will depend on the button type | |
accent | string | The accent color of the SystemIcon. This overrides | |
fillIcon | boolean | Whether the icon should received filled (colored background layer) or regular styles.
Corresponds to | |
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
as | React.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 Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | button |
ref | React.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 |
TertiaryButton
Props
Props extend from button. Changing the as prop will change the element interface.
| Name | Type | Description | Default |
|---|---|---|---|
variant | 'inverse' | Variant has an option for | |
iconPosition | 'start' | 'end' | Button icon positions can either be | 'start' |
shouldMirrorIcon | boolean | If set to | false |
shouldMirrorIconInRTL | boolean | If set to | false |
color | string | The color of the SystemIcon. This defines | |
background | string | The background color of the SystemIcon. | |
size | | There are four button sizes: | 'medium' |
icon | | The icon of the Button.
Note: Not displayed at | |
shouldMirror | boolean | If set to | false |
shouldMirrorInRTL | boolean | If set to | false |
cs | | The | |
children | ReactNode | ||
colors | | Override default colors of a button. The default will depend on the button type | |
accent | string | The accent color of the SystemIcon. This overrides | |
fillIcon | boolean | Whether the icon should received filled (colored background layer) or regular styles.
Corresponds to | |
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
as | React.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 Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | button |
ref | React.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 |
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.
| Name | Type | Description | Default |
|---|---|---|---|
variant | 'outline' | Variant has an option for | |
iconPosition | 'start' | 'end' | Button icon positions can either be | 'start' |
shouldMirrorIcon | boolean | If set to | false |
shouldMirrorIconInRTL | boolean | If set to | false |
color | string | The color of the SystemIcon. This defines | |
background | string | The background color of the SystemIcon. | |
size | | There are four button sizes: | |
icon | | The icon of the Button.
Note: Not displayed at | |
shouldMirror | boolean | If set to | false |
shouldMirrorInRTL | boolean | If set to | false |
cs | | The | |
children | ReactNode | ||
colors | | Override default colors of a button. The default will depend on the button type | |
accent | string | The accent color of the SystemIcon. This overrides | |
fillIcon | boolean | Whether the icon should received filled (colored background layer) or regular styles.
Corresponds to | |
grow | boolean | True if the component should grow to its container's width. False otherwise. | |
as | React.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 Note: Not all elements make sense and some elements may cause accessibility issues. Change this value with care. | button |
ref | React.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 |