Button API

Import

Cimpress UI exports several different button-related components. Use the version that’s appropriate for your use case.

Button: has a visible label, performs an action
LinkButton: has a visible label, performs navigation
IconButton: has no visible label (icon-only), performs an action
IconLinkButton: has no visible label (icon-only), performs navigation

import { Button, IconButton, IconLinkButton, LinkButton } from '@cimpress-ui/react';

Accessibility notes

Button and IconButton can be activated by pressing Enter or Space, similar to a native HTML button.

LinkButton and IconLinkButton can be activated by pressing Enter, similar to a native HTML link.

IconButton and IconLinkButton should have an aria-label prop defined to identify the function of the button to assistive technologies. Button and IconButton in a loading state should have a loadingLabel prop defined to identify the loading state to assistive technologies. See our accessibility guide for more details.

Buttons with a variant="tertiary" prop have a transparent background. This variant should only be used on backgrounds that provide adequate contrast.

API reference

Button

Displays a labelled button that allows users to perform an action.

See button usage guidelines.

ref Section titled “ ref ” Ref<HTMLButtonElement>: The ref type for this component.

ButtonProps

children * Section titled “ children * ” StringLikeChildren: The text displayed on the button.
variant Section titled “ variant ” 'primary' | 'secondary' | 'tertiary': Determines the visual appearance of the button.

Defaults to 'secondary' .
tone Section titled “ tone ” 'base' | 'critical': Determines the color tone of the button.

Defaults to 'base' .
size Section titled “ size ” 'small' | 'medium' | 'large': The size of the button.

Defaults to 'medium' .
fullWidth Section titled “ fullWidth ” boolean: Whether the button should take up the whole available width.

Defaults to false .
iconStart Section titled “ iconStart ” ReactNode: An icon displayed before the button text.
iconEnd Section titled “ iconEnd ” ReactNode: An icon displayed after the button text.
isLoading Section titled “ isLoading ” boolean: Whether the button is in a loading state. This disables the button and replaces its contents with a spinner.

Defaults to false .
loadingLabel Section titled “ loadingLabel ” string: A string that identifies the loading state to assistive technologies. It will be announced by screen readers together with the button label. You must provide this prop if isLoading is true.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
isDisabled Section titled “ isDisabled ” boolean: Whether the button is disabled.
type Section titled “ type ” 'button' | 'reset' | 'submit': The behavior of the button when used in an HTML form.

Defaults to 'button' .
form Section titled “ form ” string: The <form> element to associate the button with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: Submitted as a pair with the button's value as part of the form data.
value Section titled “ value ” string: The value associated with the button's name when it's submitted with the form data.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
onPress Section titled “ onPress ” (e: PressEvent) => void: Handler that is called when the press is released over the target.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

LinkButton

Displays a labelled button that allows users to navigate to another page or resource.

See button usage guidelines.

ref Section titled “ ref ” Ref<HTMLAnchorElement>: The ref type for this component.

LinkButtonProps

children * Section titled “ children * ” StringLikeChildren: The text displayed on the button.
href * Section titled “ href * ” string: A URL to link to.
variant Section titled “ variant ” 'primary' | 'secondary' | 'tertiary': Determines the visual appearance of the button.

Defaults to 'secondary' .
tone Section titled “ tone ” 'base' | 'critical': Determines the color tone of the button.

Defaults to 'base' .
size Section titled “ size ” 'small' | 'medium' | 'large': The size of the button.

Defaults to 'medium' .
fullWidth Section titled “ fullWidth ” boolean: Whether the button should take up the whole available width.

Defaults to false .
iconStart Section titled “ iconStart ” ReactNode: An icon displayed before the button text.
iconEnd Section titled “ iconEnd ” ReactNode: An icon displayed after the button text.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-label Section titled “ aria-label ” string: Defines a string value that labels the current element.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
routerOptions Section titled “ routerOptions ” undefined: Options for the configured client side router.
isDisabled Section titled “ isDisabled ” boolean: Whether the link is disabled.
hrefLang Section titled “ hrefLang ” string: Hints at the human language of the linked URL. SeeMDN.
target Section titled “ target ” HTMLAttributeAnchorTarget: The target window for the link. See MDN.
rel Section titled “ rel ” string: The relationship between the linked resource and the current page. See MDN.
download Section titled “ download ” string | boolean: Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
ping Section titled “ ping ” string: A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy Section titled “ referrerPolicy ” HTMLAttributeReferrerPolicy: How much of the referrer to send when following the link. See MDN.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

IconButton

Displays an icon-only button that allows users to perform an action.

See button usage guidelines.

ref Section titled “ ref ” Ref<HTMLButtonElement>: The ref type for this component.

IconButtonProps

icon * Section titled “ icon * ” ReactNode: The icon displayed on the button.
aria-label * Section titled “ aria-label * ” string: The label describing the function of this button for assistive technologies.
variant Section titled “ variant ” 'primary' | 'secondary' | 'tertiary': Determines the visual appearance of the button.

Defaults to 'secondary' .
tone Section titled “ tone ” 'base' | 'critical': Determines the color tone of the button.

Defaults to 'base' .
size Section titled “ size ” 'small' | 'medium' | 'large': The size of the button.

Defaults to 'medium' .
fullWidth Section titled “ fullWidth ” boolean: Whether the button should take up the whole available width.

Defaults to false .
isLoading Section titled “ isLoading ” boolean: Whether the button is in a loading state. This disables the button and replaces its contents with a spinner.

Defaults to false .
loadingLabel Section titled “ loadingLabel ” string: A string that identifies the loading state to assistive technologies. It will be announced by screen readers together with the button label. You must provide this prop if isLoading is true.
id Section titled “ id ” string: The element's unique identifier. See MDN.
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
isDisabled Section titled “ isDisabled ” boolean: Whether the button is disabled.
type Section titled “ type ” 'button' | 'reset' | 'submit': The behavior of the button when used in an HTML form.

Defaults to 'button' .
form Section titled “ form ” string: The <form> element to associate the button with. The value of this attribute must be the id of a <form> in the same document. See MDN.
name Section titled “ name ” string: Submitted as a pair with the button's value as part of the form data.
value Section titled “ value ” string: The value associated with the button's name when it's submitted with the form data.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.
onPress Section titled “ onPress ” (e: PressEvent) => void: Handler that is called when the press is released over the target.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

IconLinkButton

Displays an icon-only button that allows users to navigate to another page or resource.

See button usage guidelines.

ref Section titled “ ref ” Ref<HTMLAnchorElement>: The ref type for this component.

IconLinkButtonProps

icon * Section titled “ icon * ” ReactNode: The icon displayed on the button.
aria-label * Section titled “ aria-label * ” string: The label describing the function of this button for assistive technologies.
href * Section titled “ href * ” string: A URL to link to.
variant Section titled “ variant ” 'primary' | 'secondary' | 'tertiary': Determines the visual appearance of the button.

Defaults to 'secondary' .
tone Section titled “ tone ” 'base' | 'critical': Determines the color tone of the button.

Defaults to 'base' .
size Section titled “ size ” 'small' | 'medium' | 'large': The size of the button.

Defaults to 'medium' .
fullWidth Section titled “ fullWidth ” boolean: Whether the button should take up the whole available width.

Defaults to false .
data-cim-style-root Section titled “ data-cim-style-root ” boolean: Use this attribute to "claim" the component tree for exclusive Cimpress UI usage.
UNSAFE_className Section titled “ UNSAFE_className ” string: Sets the CSS className for the element. Only use as a last resort. Use style props instead.

See styling guide.
UNSAFE_style Section titled “ UNSAFE_style ” CSSProperties: Sets the CSS style for the element. Only use as a last resort. Use style props instead.

See styling guide.
aria-labelledby Section titled “ aria-labelledby ” string: Identifies the element (or elements) that labels the current element.
aria-describedby Section titled “ aria-describedby ” string: Identifies the element (or elements) that describes the object.
aria-details Section titled “ aria-details ” string: Identifies the element (or elements) that provide a detailed, extended description for the object.
routerOptions Section titled “ routerOptions ” undefined: Options for the configured client side router.
isDisabled Section titled “ isDisabled ” boolean: Whether the link is disabled.
hrefLang Section titled “ hrefLang ” string: Hints at the human language of the linked URL. SeeMDN.
target Section titled “ target ” HTMLAttributeAnchorTarget: The target window for the link. See MDN.
rel Section titled “ rel ” string: The relationship between the linked resource and the current page. See MDN.
download Section titled “ download ” string | boolean: Causes the browser to download the linked URL. A string may be provided to suggest a file name. See MDN.
ping Section titled “ ping ” string: A space-separated list of URLs to ping when the link is followed. See MDN.
referrerPolicy Section titled “ referrerPolicy ” HTMLAttributeReferrerPolicy: How much of the referrer to send when following the link. See MDN.
onHoverStart Section titled “ onHoverStart ” (e: HoverEvent) => void: Handler that is called when a hover interaction starts.
onHoverEnd Section titled “ onHoverEnd ” (e: HoverEvent) => void: Handler that is called when a hover interaction ends.

StyleProps

margin Section titled “ margin ” Responsive<Spacing | "auto">: The amount of margin applied to all edges of this component.
marginX Section titled “ marginX ” Responsive<Spacing | "auto">: The amount of margin applied to the left and right edges of this component. Takes priority over margin.
marginY Section titled “ marginY ” Responsive<Spacing | "auto">: The amount of margin applied to the top and bottom edges of this component. Takes priority over margin.
marginTop Section titled “ marginTop ” Responsive<Spacing | "auto">: The amount of margin applied to the top edge of this component. Takes priority over marginY and margin.
marginRight Section titled “ marginRight ” Responsive<Spacing | "auto">: The amount of margin applied to the right edge of this component. Takes priority over marginX and margin.
marginBottom Section titled “ marginBottom ” Responsive<Spacing | "auto">: The amount of margin applied to the bottom edge of this component. Takes priority over marginY and margin.
marginLeft Section titled “ marginLeft ” Responsive<Spacing | "auto">: The amount of margin applied to the left edge of this component. Takes priority over marginX and margin.

Button API

Import

Accessibility notes

API reference

Button

ref

children *

variant

tone

size

fullWidth

iconStart

iconEnd

isLoading

loadingLabel

id

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

isDisabled

type

form

name

value

onHoverStart

onHoverEnd

onPress

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

LinkButton

ref

children *

href *

variant

tone

size

fullWidth

iconStart

iconEnd

data-cim-style-root

UNSAFE_className

UNSAFE_style

aria-label

aria-labelledby

aria-describedby

aria-details

routerOptions

isDisabled

hrefLang

target

rel

download

ping

referrerPolicy

onHoverStart

onHoverEnd

margin

marginX

marginY

marginTop

marginRight

marginBottom

marginLeft

IconButton

ref

icon *

aria-label *

variant

tone

size

fullWidth